class Ec2TaskDefinition (construct)
Language | Type name |
---|---|
![]() | Amazon.CDK.AWS.ECS.Ec2TaskDefinition |
![]() | github.com/aws/aws-cdk-go/awscdk/v2/awsecs#Ec2TaskDefinition |
![]() | software.amazon.awscdk.services.ecs.Ec2TaskDefinition |
![]() | aws_cdk.aws_ecs.Ec2TaskDefinition |
![]() | aws-cdk-lib » aws_ecs » Ec2TaskDefinition |
Implements
IConstruct
, IDependable
, IResource
, ITask
, IEc2
The details of a task definition run on an EC2 cluster.
Example
declare const secret: ecs.Secret;
// Create a Task Definition for the container to start
const taskDefinition = new ecs.Ec2TaskDefinition(this, 'TaskDef');
taskDefinition.addContainer('TheContainer', {
image: ecs.ContainerImage.fromRegistry('example-image'),
memoryLimitMiB: 256,
logging: ecs.LogDrivers.splunk({
secretToken: secret,
url: 'my-splunk-url',
}),
});
Initializer
new Ec2TaskDefinition(scope: Construct, id: string, props?: Ec2TaskDefinitionProps)
Parameters
- scope
Construct
- id
string
- props
Ec2
Task Definition Props
Constructs a new instance of the Ec2TaskDefinition class.
Construct Props
Name | Type | Description |
---|---|---|
enable | boolean | Enables fault injection and allows for fault injection requests to be accepted from the task's containers. |
execution | IRole | The name of the IAM task execution role that grants the ECS agent permission to call AWS APIs on your behalf. |
family? | string | The name of a family that this task definition is registered to. |
inference | Inference [] | The inference accelerators to use for the containers in the task. |
ipc | Ipc | The IPC resource namespace to use for the containers in the task. |
network | Network | The Docker networking mode to use for the containers in the task. |
pid | Pid | The process namespace to use for the containers in the task. |
placement | Placement [] | An array of placement constraint objects to use for the task. |
proxy | Proxy | The configuration details for the App Mesh proxy. |
task | IRole | The name of the IAM role that grants containers in the task permission to call AWS APIs on your behalf. |
volumes? | Volume [] | The list of volume definitions for the task. |
enableFaultInjection?
Type:
boolean
(optional, default: undefined - ECS default setting is false)
Enables fault injection and allows for fault injection requests to be accepted from the task's containers.
Fault injection only works with tasks using the {@link NetworkMode.AWS_VPC} or {@link NetworkMode.HOST} network modes.
executionRole?
Type:
IRole
(optional, default: An execution role will be automatically created if you use ECR images in your task definition.)
The name of the IAM task execution role that grants the ECS agent permission to call AWS APIs on your behalf.
The role will be used to retrieve container images from ECR and create CloudWatch log groups.
family?
Type:
string
(optional, default: Automatically generated name.)
The name of a family that this task definition is registered to.
A family groups multiple versions of a task definition.
inferenceAccelerators?
Type:
Inference
[]
(optional, default: No inference accelerators.)
The inference accelerators to use for the containers in the task.
Not supported in Fargate.
ipcMode?
Type:
Ipc
(optional, default: IpcMode used by the task is not specified)
The IPC resource namespace to use for the containers in the task.
Not supported in Fargate and Windows containers.
networkMode?
Type:
Network
(optional, default: NetworkMode.BRIDGE for EC2 tasks, AWS_VPC for Fargate tasks.)
The Docker networking mode to use for the containers in the task.
The valid values are NONE, BRIDGE, AWS_VPC, and HOST.
pidMode?
Type:
Pid
(optional, default: PidMode used by the task is not specified)
The process namespace to use for the containers in the task.
Not supported in Windows containers.
placementConstraints?
Type:
Placement
[]
(optional, default: No placement constraints.)
An array of placement constraint objects to use for the task.
You can specify a maximum of 10 constraints per task (this limit includes constraints in the task definition and those specified at run time).
proxyConfiguration?
Type:
Proxy
(optional, default: No proxy configuration.)
The configuration details for the App Mesh proxy.
taskRole?
Type:
IRole
(optional, default: A task role is automatically created for you.)
The name of the IAM role that grants containers in the task permission to call AWS APIs on your behalf.
volumes?
Type:
Volume
[]
(optional, default: No volumes are passed to the Docker daemon on a container instance.)
The list of volume definitions for the task.
For more information, see Task Definition Parameter Volumes.
Properties
Name | Type | Description |
---|---|---|
compatibility | Compatibility | The task launch type compatibility requirement. |
env | Resource | The environment this resource belongs to. |
family | string | The name of a family that this task definition is registered to. |
inference | Inference [] | Public getter method to access list of inference accelerators attached to the instance. |
is | boolean | Return true if the task definition can be run on an EC2 cluster. |
is | boolean | Return true if the task definition can be run on a ECS anywhere cluster. |
is | boolean | Return true if the task definition can be run on a Fargate cluster. |
network | Network | The networking mode to use for the containers in the task. |
node | Node | The tree node. |
stack | Stack | The stack in which this resource is defined. |
task | string | The full Amazon Resource Name (ARN) of the task definition. |
task | IRole | The name of the IAM role that grants containers in the task permission to call AWS APIs on your behalf. |
default | Container | Default container for this task. |
ephemeral | number | The amount (in GiB) of ephemeral storage to be allocated to the task. |
execution | IRole | Execution role for this task definition. |
pid | Pid | The process namespace to use for the containers in the task. |
references | boolean | Whether this task definition has at least a container that references a specific JSON field of a secret stored in Secrets Manager. |
compatibility
Type:
Compatibility
The task launch type compatibility requirement.
env
Type:
Resource
The environment this resource belongs to.
For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.
family
Type:
string
The name of a family that this task definition is registered to.
A family groups multiple versions of a task definition.
inferenceAccelerators
Type:
Inference
[]
Public getter method to access list of inference accelerators attached to the instance.
isEc2Compatible
Type:
boolean
Return true if the task definition can be run on an EC2 cluster.
isExternalCompatible
Type:
boolean
Return true if the task definition can be run on a ECS anywhere cluster.
isFargateCompatible
Type:
boolean
Return true if the task definition can be run on a Fargate cluster.
networkMode
Type:
Network
The networking mode to use for the containers in the task.
node
Type:
Node
The tree node.
stack
Type:
Stack
The stack in which this resource is defined.
taskDefinitionArn
Type:
string
The full Amazon Resource Name (ARN) of the task definition.
taskRole
Type:
IRole
The name of the IAM role that grants containers in the task permission to call AWS APIs on your behalf.
defaultContainer?
Type:
Container
(optional)
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.
ephemeralStorageGiB?
Type:
number
(optional)
The amount (in GiB) of ephemeral storage to be allocated to the task.
Only supported in Fargate platform version 1.4.0 or later.
executionRole?
Type:
IRole
(optional)
Execution role for this task definition.
pidMode?
Type:
Pid
(optional)
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.
referencesSecretJsonField?
Type:
boolean
(optional)
Whether this task definition has at least a container that references a specific JSON field of a secret stored in Secrets Manager.
Methods
Name | Description |
---|---|
add | Tasks running in AWSVPC networking mode requires an additional environment variable for the region to be sourced. |
add | Adds the specified extension to the task definition. |
add | Adds a firelens log router to the task definition. |
add | Adds an inference accelerator to the task definition. |
add | Adds the specified placement constraint to the task definition. |
add | Adds a policy statement to the task execution IAM role. |
add | Adds a policy statement to the task IAM role. |
add | Adds a volume to the task definition. |
apply | Apply the given removal policy to this resource. |
find | Returns the container that match the provided containerName. |
find | Determine the existing port mapping for the provided name. |
grant | Grants permissions to run this task definition. |
obtain | Creates the task execution IAM role if it doesn't already exist. |
to | Returns a string representation of this construct. |
static from | Imports a task definition from the specified task definition ARN. |
static from | Imports an existing Ec2 task definition from its attributes. |
addContainer(id, props)
public addContainer(id: string, props: ContainerDefinitionOptions): ContainerDefinition
Parameters
- id
string
- props
Container
Definition Options
Returns
Tasks running in AWSVPC networking mode requires an additional environment variable for the region to be sourced.
This override adds in the additional environment variable as required
addExtension(extension)
public addExtension(extension: ITaskDefinitionExtension): void
Parameters
- extension
ITask
Definition Extension
Adds the specified extension to the task definition.
Extension can be used to apply a packaged modification to a task definition.
addFirelensLogRouter(id, props)
public addFirelensLogRouter(id: string, props: FirelensLogRouterDefinitionOptions): FirelensLogRouter
Parameters
- id
string
- props
Firelens
Log Router Definition Options
Returns
Adds a firelens log router to the task definition.
addInferenceAccelerator(inferenceAccelerator)
public addInferenceAccelerator(inferenceAccelerator: InferenceAccelerator): void
⚠️ Deprecated: ECS TaskDefinition's inferenceAccelerator is EOL since April 2024
Parameters
- inferenceAccelerator
Inference
Accelerator
Adds an inference accelerator to the task definition.
addPlacementConstraint(constraint)
public addPlacementConstraint(constraint: PlacementConstraint): void
Parameters
- constraint
Placement
Constraint
Adds the specified placement constraint to the task definition.
addToExecutionRolePolicy(statement)
public addToExecutionRolePolicy(statement: PolicyStatement): void
Parameters
- statement
Policy
Statement
Adds a policy statement to the task execution IAM role.
addToTaskRolePolicy(statement)
public addToTaskRolePolicy(statement: PolicyStatement): void
Parameters
- statement
Policy
Statement
Adds a policy statement to the task IAM role.
addVolume(volume)
public addVolume(volume: Volume): void
Parameters
- volume
Volume
Adds a volume to the task definition.
applyRemovalPolicy(policy)
public applyRemovalPolicy(policy: RemovalPolicy): void
Parameters
- policy
Removal
Policy
Apply the given removal policy to this resource.
The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.
The resource can be deleted (RemovalPolicy.DESTROY
), or left in your AWS
account for data recovery and cleanup later (RemovalPolicy.RETAIN
).
findContainer(containerName)
public findContainer(containerName: string): ContainerDefinition
Parameters
- containerName
string
Returns
Returns the container that match the provided containerName.
findPortMappingByName(name)
public findPortMappingByName(name: string): PortMapping
Parameters
- name
string
— : port mapping name.
Returns
Determine the existing port mapping for the provided name.
grantRun(grantee)
public grantRun(grantee: IGrantable): Grant
Parameters
- grantee
IGrantable
— Principal to grant consume rights to.
Returns
Grants permissions to run this task definition.
This will grant the following permissions:
- ecs:RunTask
- iam:PassRole
obtainExecutionRole()
public obtainExecutionRole(): IRole
Returns
Creates the task execution IAM role if it doesn't already exist.
toString()
public toString(): string
Returns
string
Returns a string representation of this construct.
static fromEc2TaskDefinitionArn(scope, id, ec2TaskDefinitionArn)
public static fromEc2TaskDefinitionArn(scope: Construct, id: string, ec2TaskDefinitionArn: string): IEc2TaskDefinition
Parameters
- scope
Construct
- id
string
- ec2TaskDefinitionArn
string
Returns
Imports a task definition from the specified task definition ARN.
static fromEc2TaskDefinitionAttributes(scope, id, attrs)
public static fromEc2TaskDefinitionAttributes(scope: Construct, id: string, attrs: Ec2TaskDefinitionAttributes): IEc2TaskDefinition
Parameters
- scope
Construct
- id
string
- attrs
Ec2
Task Definition Attributes
Returns
Imports an existing Ec2 task definition from its attributes.