TaskDefinition

class aws_cdk.aws_ecs.TaskDefinition(scope, id, *, compatibility, cpu=None, memory_mib=None, network_mode=None, placement_constraints=None, execution_role=None, family=None, proxy_configuration=None, task_role=None, volumes=None)

Bases: aws_cdk.core.Resource

The base class for all task definitions.

__init__(scope, id, *, compatibility, cpu=None, memory_mib=None, network_mode=None, placement_constraints=None, execution_role=None, family=None, proxy_configuration=None, task_role=None, volumes=None)

Constructs a new instance of the TaskDefinition class.

Parameters
  • scope (Construct) –

  • id (str) –

  • props

  • compatibility (Compatibility) – The task launch type compatiblity requirement.

  • cpu (Optional[str]) – The number of cpu units used by the task. 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) Default: - CPU units are not specified.

  • memory_mib (Optional[str]) – The amount (in MiB) of memory used by the task. 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) Default: - Memory used by task is not specified.

  • network_mode (Optional[NetworkMode]) – The networking mode to use for the containers in the task. On Fargate, the only supported networking mode is AwsVpc. Default: - NetworkMode.Bridge for EC2 tasks, AwsVpc for Fargate tasks.

  • placement_constraints (Optional[List[PlacementConstraint]]) – The placement constraints to use for tasks in the service. 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. Default: - No placement constraints.

  • execution_role (Optional[IRole]) – The name of the IAM task execution role that grants the ECS agent to call AWS APIs on your behalf. The role will be used to retrieve container images from ECR and create CloudWatch log groups. Default: - An execution role will be automatically created if you use ECR images in your task definition.

  • family (Optional[str]) – The name of a family that this task definition is registered to. A family groups multiple versions of a task definition. Default: - Automatically generated name.

  • proxy_configuration (Optional[ProxyConfiguration]) – The configuration details for the App Mesh proxy. Default: - No proxy configuration.

  • task_role (Optional[IRole]) – 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 (Optional[List[Volume]]) – The list of volume definitions for the task. For more information, see Task Definition Parameter Volumes. Default: - No volumes are passed to the Docker daemon on a container instance.

Return type

None

Methods

add_container(id, *, image, command=None, cpu=None, disable_networking=None, dns_search_domains=None, dns_servers=None, docker_labels=None, docker_security_options=None, entry_point=None, environment=None, essential=None, extra_hosts=None, gpu_count=None, health_check=None, hostname=None, linux_parameters=None, logging=None, memory_limit_mib=None, memory_reservation_mib=None, privileged=None, readonly_root_filesystem=None, secrets=None, start_timeout=None, stop_timeout=None, user=None, working_directory=None)

Adds a new container to the task definition.

Parameters
  • id (str) –

  • props

  • image (ContainerImage) – The image used to start a container. This string is passed directly to the Docker daemon. Images in the Docker Hub registry are available by default. Other repositories are specified with either repository-url/image:tag or repository-url/image@digest. TODO: Update these to specify using classes of IContainerImage

  • command (Optional[List[str]]) – The command that is passed to the container. If you provide a shell command as a single string, you have to quote command-line arguments. Default: - CMD value built into container image.

  • cpu (Union[int, float, None]) – The minimum number of CPU units to reserve for the container. Default: - No minimum CPU units reserved.

  • disable_networking (Optional[bool]) – Specifies whether networking is disabled within the container. When this parameter is true, networking is disabled within the container. Default: false

  • dns_search_domains (Optional[List[str]]) – A list of DNS search domains that are presented to the container. Default: - No search domains.

  • dns_servers (Optional[List[str]]) – A list of DNS servers that are presented to the container. Default: - Default DNS servers.

  • docker_labels (Optional[Mapping[str, str]]) – A key/value map of labels to add to the container. Default: - No labels.

  • docker_security_options (Optional[List[str]]) – A list of strings to provide custom labels for SELinux and AppArmor multi-level security systems. Default: - No security labels.

  • entry_point (Optional[List[str]]) – The ENTRYPOINT value to pass to the container. Default: - Entry point configured in container.

  • environment (Optional[Mapping[str, str]]) – The environment variables to pass to the container. Default: - No environment variables.

  • essential (Optional[bool]) – Specifies whether the container is marked essential. If the essential parameter of a container is marked as true, and that container fails or stops for any reason, all other containers that are part of the task are stopped. If the essential parameter of a container is marked as false, then its failure does not affect the rest of the containers in a task. All tasks must have at least one essential container. If this parameter is omitted, a container is assumed to be essential. Default: true

  • extra_hosts (Optional[Mapping[str, str]]) – A list of hostnames and IP address mappings to append to the /etc/hosts file on the container. Default: - No extra hosts.

  • gpu_count (Union[int, float, None]) – The number of GPUs assigned to the container. Default: - No GPUs assigned.

  • health_check (Optional[HealthCheck]) – The health check command and associated configuration parameters for the container. Default: - Health check configuration from container.

  • hostname (Optional[str]) – The hostname to use for your container. Default: - Automatic hostname.

  • linux_parameters (Optional[LinuxParameters]) – Linux-specific modifications that are applied to the container, such as Linux kernel capabilities. For more information see KernelCapabilities. Default: - No Linux paramters.

  • logging (Optional[LogDriver]) – The log configuration specification for the container. Default: - Containers use the same logging driver that the Docker daemon uses.

  • memory_limit_mib (Union[int, float, None]) – The amount (in MiB) of memory to present to the container. If your container attempts to exceed the allocated memory, the container is terminated. At least one of memoryLimitMiB and memoryReservationMiB is required for non-Fargate services. Default: - No memory limit.

  • memory_reservation_mib (Union[int, float, None]) – The soft limit (in MiB) of memory to reserve for the container. When system memory is under heavy contention, Docker attempts to keep the container memory to this soft limit. However, your container can consume more memory when it needs to, up to either the hard limit specified with the memory parameter (if applicable), or all of the available memory on the container instance, whichever comes first. At least one of memoryLimitMiB and memoryReservationMiB is required for non-Fargate services. Default: - No memory reserved.

  • privileged (Optional[bool]) – Specifies whether the container is marked as privileged. When this parameter is true, the container is given elevated privileges on the host container instance (similar to the root user). Default: false

  • readonly_root_filesystem (Optional[bool]) – When this parameter is true, the container is given read-only access to its root file system. Default: false

  • secrets (Optional[Mapping[str, Secret]]) – The secret environment variables to pass to the container. Default: - No secret environment variables.

  • start_timeout (Optional[Duration]) – Time duration (in seconds) to wait before giving up on resolving dependencies for a container. Default: - none

  • stop_timeout (Optional[Duration]) – Time duration (in seconds) to wait before the container is forcefully killed if it doesn’t exit normally on its own. Default: - none

  • user (Optional[str]) – The user name to use inside the container. Default: root

  • working_directory (Optional[str]) – The working directory in which to run commands inside the container. Default: /

Return type

ContainerDefinition

add_extension(extension)

Adds the specified extention to the task definition.

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

Parameters

extension (ITaskDefinitionExtension) –

Return type

None

add_placement_constraint(constraint)

Adds the specified placement constraint to the task definition.

Parameters

constraint (PlacementConstraint) –

Return type

None

add_to_execution_role_policy(statement)

Adds a policy statement to the task execution IAM role.

Parameters

statement (PolicyStatement) –

Return type

None

add_to_task_role_policy(statement)

Adds a policy statement to the task IAM role.

Parameters

statement (PolicyStatement) –

Return type

None

add_volume(*, name, docker_volume_configuration=None, host=None)

Adds a volume to the task definition.

Parameters
  • volume

  • name (str) – The name of the volume. Up to 255 letters (uppercase and lowercase), numbers, and hyphens are allowed. This name is referenced in the sourceVolume parameter of container definition mountPoints.

  • docker_volume_configuration (Optional[DockerVolumeConfiguration]) – This property is specified when you are using Docker volumes. Docker volumes are only supported when you are using the EC2 launch type. Windows containers only support the use of the local driver. To use bind mounts, specify a host instead.

  • host (Optional[Host]) – This property is specified when you are using bind mount host volumes. Bind mount host volumes are supported when you are using either the EC2 or Fargate launch types. The contents of the host parameter determine whether your bind mount host volume persists on the host container instance and where it is stored. If the host parameter is empty, then the Docker daemon assigns a host path for your data volume. However, the data is not guaranteed to persist after the containers associated with it stop running.

Return type

None

obtain_execution_role()

Creates the task execution IAM role if it doesn’t already exist.

Return type

IRole

to_string()

Returns a string representation of this construct.

Return type

str

Attributes

compatibility

The task launch type compatiblity requirement.

Return type

Compatibility

default_container

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.

Return type

Optional[ContainerDefinition]

execution_role

Execution role for this task definition.

Return type

Optional[IRole]

family

The name of a family that this task definition is registered to. A family groups multiple versions of a task definition.

Return type

str

is_ec2_compatible

Return true if the task definition can be run on an EC2 cluster.

Return type

bool

is_fargate_compatible

Return true if the task definition can be run on a Fargate cluster.

Return type

bool

network_mode

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

Return type

NetworkMode

node

Construct tree node which offers APIs for interacting with the construct tree.

Return type

ConstructNode

stack

The stack in which this resource is defined.

Return type

Stack

task_definition_arn

The full Amazon Resource Name (ARN) of the task definition.

attribute: :attribute:: true

Return type

str

task_role

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

Return type

IRole

Static Methods

classmethod from_task_definition_arn(scope, id, task_definition_arn)

Imports a task definition from the specified task definition ARN.

The task will have a compatibility of EC2+Fargate.

Parameters
  • scope (Construct) –

  • id (str) –

  • task_definition_arn (str) –

Return type

ITaskDefinition

classmethod is_construct(x)

Return whether the given object is a Construct.

Parameters

x (Any) –

Return type

bool