CloudWiki

Amazon Web Service (AWS)

ECS Task Definition

Compute
An ECS task definition is a blueprint that describes the parameters for your application in JSON-formatted text, within one or more containers. Examples of task definition parameters can be which launch type to use, which ports should be opened , what data volumes should be used, CPU and memory requirements, what commands to run, and which environmental variables to be used.
aws_ecs_task_definition
ECS Task Definition
attributes:

The following arguments are required:

  • container_definitions - (Required) A list of valid container definitions provided as a single valid JSON document. Please note that you should only provide values that are part of the container definition document. For a detailed description of what parameters are available, see the Task Definition Parameters section from the official Developer Guide.
  • family - (Required) A unique name for your task definition.

The following arguments are optional:

  • cpu - (Optional) Number of cpu units used by the task. If the requires_compatibilities is FARGATE this field is required.
  • execution_role_arn - (Optional) ARN of the task execution role that the Amazon ECS container agent and the Docker daemon can assume.
  • inference_accelerator - (Optional) Configuration block(s) with Inference Accelerators settings. Detailed below.
  • ipc_mode - (Optional) IPC resource namespace to be used for the containers in the task The valid values are host, task, and none.
  • memory - (Optional) Amount (in MiB) of memory used by the task. If the requires_compatibilities is FARGATE this field is required.
  • network_mode - (Optional) Docker networking mode to use for the containers in the task. Valid values are none, bridge, awsvpc, and host.
  • runtime_platform - (Optional) Configuration block for runtime_platform that containers in your task may use.
  • pid_mode - (Optional) Process namespace to use for the containers in the task. The valid values are host and task.
  • placement_constraints - (Optional) Configuration block for rules that are taken into consideration during task placement. Maximum number of placement_constraints is 10. Detailed below.
  • proxy_configuration - (Optional) Configuration block for the App Mesh proxy. Detailed below.
  • ephemeral_storage - (Optional) The amount of ephemeral storage to allocate for the task. This parameter is used to expand the total amount of ephemeral storage available, beyond the default amount, for tasks hosted on AWS Fargate. See Ephemeral Storage.
  • requires_compatibilities - (Optional) Set of launch types required by the task. The valid values are EC2 and FARGATE.
  • skip_destroy - (Optional) Whether to retain the old revision when the resource is destroyed or replacement is necessary. Default is false.
  • tags - (Optional) Key-value map of resource tags. If configured with a provider default_tags configuration block present, tags with matching keys will overwrite those defined at the provider-level.
  • task_role_arn - (Optional) ARN of IAM role that allows your Amazon ECS container task to make calls to other AWS services.
  • volume - (Optional) Configuration block for volumes that containers in your task may use. Detailed below.

volume

  • docker_volume_configuration - (Optional) Configuration block to configure a docker volume. Detailed below.
  • efs_volume_configuration - (Optional) Configuration block for an EFS volume. Detailed below.
  • fsx_windows_file_server_volume_configuration - (Optional) Configuration block for an FSX Windows File Server volume. Detailed below.
  • host_path - (Optional) Path on the host container instance that is presented to the container. If not set, ECS will create a nonpersistent data volume that starts empty and is deleted after the task has finished.
  • name - (Required) Name of the volume. This name is referenced in the sourceVolume parameter of container definition in the mountPoints section.

docker_volume_configuration

For more information, see Specifying a Docker volume in your Task Definition Developer Guide

  • autoprovision - (Optional) If this value is true, the Docker volume is created if it does not already exist. Note: This field is only used if the scope is shared.
  • driver_opts - (Optional) Map of Docker driver specific options.
  • driver - (Optional) Docker volume driver to use. The driver value must match the driver name provided by Docker because it is used for task placement.
  • labels - (Optional) Map of custom metadata to add to your Docker volume.
  • scope - (Optional) Scope for the Docker volume, which determines its lifecycle, either task or shared. Docker volumes that are scoped to a task are automatically provisioned when the task starts and destroyed when the task stops. Docker volumes that are scoped as shared persist after the task stops.

efs_volume_configuration

For more information, see Specifying an EFS volume in your Task Definition Developer Guide

  • file_system_id - (Required) ID of the EFS File System.
  • root_directory - (Optional) Directory within the Amazon EFS file system to mount as the root directory inside the host. If this parameter is omitted, the root of the Amazon EFS volume will be used. Specifying / will have the same effect as omitting this parameter. This argument is ignored when using authorization_config.
  • transit_encryption - (Optional) Whether or not to enable encryption for Amazon EFS data in transit between the Amazon ECS host and the Amazon EFS server. Transit encryption must be enabled if Amazon EFS IAM authorization is used. Valid values: ENABLED, DISABLED. If this parameter is omitted, the default value of DISABLED is used.
  • transit_encryption_port - (Optional) Port to use for transit encryption. If you do not specify a transit encryption port, it will use the port selection strategy that the Amazon EFS mount helper uses.
  • authorization_config - (Optional) Configuration block for authorization for the Amazon EFS file system. Detailed below.

runtime_platform

  • operating_system_family - (Optional) If the requires_compatibilities is FARGATE this field is required; must be set to a valid option from the operating system family in the runtime platform setting
  • cpu_architecture - (Optional) Must be set to either X86_64 or ARM64; see cpu architecture

authorization_config

  • access_point_id - (Optional) Access point ID to use. If an access point is specified, the root directory value will be relative to the directory set for the access point. If specified, transit encryption must be enabled in the EFSVolumeConfiguration.
  • iam - (Optional) Whether or not to use the Amazon ECS task IAM role defined in a task definition when mounting the Amazon EFS file system. If enabled, transit encryption must be enabled in the EFSVolumeConfiguration. Valid values: ENABLED, DISABLED. If this parameter is omitted, the default value of DISABLED is used.

fsx_windows_file_server_volume_configuration

For more information, see Specifying an FSX Windows File Server volume in your Task Definition Developer Guide

  • file_system_id - (Required) The Amazon FSx for Windows File Server file system ID to use.
  • root_directory - (Required) The directory within the Amazon FSx for Windows File Server file system to mount as the root directory inside the host.
  • authorization_config - (Required) Configuration block for authorization for the Amazon FSx for Windows File Server file system detailed below.

authorization_config

  • credentials_parameter - (Required) The authorization credential option to use. The authorization credential options can be provided using either the Amazon Resource Name (ARN) of an AWS Secrets Manager secret or AWS Systems Manager Parameter Store parameter. The ARNs refer to the stored credentials.
  • domain - (Required) A fully qualified domain name hosted by an AWS Directory Service Managed Microsoft AD (Active Directory) or self-hosted AD on Amazon EC2.

placement_constraints

  • expression - (Optional) Cluster Query Language expression to apply to the constraint. For more information, see Cluster Query Language in the Amazon EC2 Container Service Developer Guide.
  • type - (Required) Type of constraint. Use memberOf to restrict selection to a group of valid candidates. Note that distinctInstance is not supported in task definitions.

proxy_configuration

  • container_name - (Required) Name of the container that will serve as the App Mesh proxy.
  • properties - (Required) Set of network configuration parameters to provide the Container Network Interface (CNI) plugin, specified a key-value mapping.
  • type - (Optional) Proxy type. The default value is APPMESH. The only supported value is APPMESH.

ephemeral_storage

  • size_in_gib - (Required) The total amount, in GiB, of ephemeral storage to set for the task. The minimum supported value is 21 GiB and the maximum supported value is 200 GiB.

inference_accelerator

  • device_name - (Required) Elastic Inference accelerator device name. The deviceName must also be referenced in a container definition as a ResourceRequirement.
  • device_type - (Required) Elastic Inference accelerator type to use.

Associating resources with a
ECS Task Definition
Resources do not "belong" to a
ECS Task Definition
Rather, one or more Security Groups are associated to a resource.
Create
ECS Task Definition
via Terraform:
The following HCL register a task definition with a JSON code
Syntax:

resource "aws_ecs_task_definition" "service" {
 family = "service"
 container_definitions = jsonencode([
   {
     name      = "first"
     image     = "service-first"
     cpu       = 10
     memory    = 512
     essential = true
     portMappings = [
       {
         containerPort = 80
         hostPort      = 80
       }
     ]
   },
   {
     name      = "second"
     image     = "service-second"
     cpu       = 10
     memory    = 256
     essential = true
     portMappings = [
       {
         containerPort = 443
         hostPort      = 443
       }
     ]
   }
 ])

 volume {
   name      = "service-storage"
   host_path = "/ecs/service-storage"
 }

 placement_constraints {
   type       = "memberOf"
   expression = "attribute:ecs.availability-zone in [us-west-2a, us-west-2b]"
 }
}

Create
ECS Task Definition
via CLI:
Parametres:

register-task-definition
--family <value>
[--task-role-arn <value>]
[--execution-role-arn <value>]
[--network-mode <value>]
--container-definitions <value>
[--volumes <value>]
[--placement-constraints <value>]
[--requires-compatibilities <value>]
[--cpu <value>]
[--memory <value>]
[--tags <value>]
[--pid-mode <value>]
[--ipc-mode <value>]
[--proxy-configuration <value>]
[--inference-accelerators <value>]
[--ephemeral-storage <value>]
[--runtime-platform <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]

Example:

aws ecs register-task-definition \    --cli-input-json file://<path_to_json_file>/sleep360.json

Best Practices for
ECS Task Definition

Categorized by Availability, Security & Compliance and Cost

Warning
Ensure each ECS Container image has a pinned (tag) version
No items found.
Explore all the rules our platform covers
All Resources