Fargate task definition considerations

Tasks that use the Fargate launch type don't support all of the Amazon ECS task definition parameters that are available. Some parameters aren't supported at all, and others behave differently for Fargate tasks.

The following task definition parameters aren't valid in Linux Fargate tasks:

• devices

• disableNetworking

• dnsSearchDomains

• dnsServers

• dockerSecurityOptions

• dockerVolumeConfiguration

• extraHosts

• gpu

• host

• hostname

• links

• placementConstraints — By default, Fargate tasks are spread across multiple Availability Zones.

• privileged

• sharedMemorySize

• tmpfs

Important

If one of the task definition parameters isn't supported, the subflags for that parameter likely aren't supported either.

The following task definition parameters behave differently for Fargate tasks:

• When using logConfiguration, the supported log drivers for Fargate tasks are the awslogs, splunk, and awsfirelens log drivers.

  Windows tasks don't support awsfirelens log drivers.

• When using linuxParameters for capabilities, the drop parameter can be used, but the add parameter isn't supported.

• The healthCheck parameter is supported only for Fargate tasks that use the platform version 1.1.0 or later.

• If you use the portMappings parameter, specify containerPort only. You can either keep hostPort blank or set it to the same value as containerPort.

• The operatingSystemFamily parameter is required for tasks that run on Linux containers and Windows containers.

To ensure that your task definition validates for use with the Fargate launch type, you can specify the following when you register the task definition:

• In the AWS Management Console, for the Requires Compatibilities field, specify FARGATE.

• In the AWS CLI, for the --requires-compatibilities option, specify FARGATE.

• In the API, specify the requiresCompatibilities flag.

Network mode

Fargate task definitions require that the network mode is set to awsvpc. The awsvpc network mode provides each task with its own elastic network interface. A network configuration is also required when creating a service or manually running tasks. For more information, see Fargate Task Networking in the Amazon Elastic Container Service User Guide for AWS Fargate.

Task CPU and memory

For Fargate task definitions, you're required to specify CPU and memory at the task level. You can also specify CPU and memory at the container level for Fargate tasks. However, doing so isn't required. For most use cases, it's OK to specify these resources at the task level only. You can find examples of specifying CPU and memory at the container level in Example task definitions.

The following table shows the valid combinations of task-level CPU and memory. The memory values in the JSON file are specified in MiB. You can convert the GB value to MiB by multiplying the value by 1024. For example 1 GB = 1024 MiB.

CPU value	Memory value	Operating systems supported for AWS Fargate
256 (.25 vCPU)	512 MiB, 1 GB, 2 GB	Linux
512 (.5 vCPU)	1 GB, 2 GB, 3 GB, 4 GB	Linux
1024 (1 vCPU)	2 GB, 3 GB, 4 GB, 5 GB, 6 GB, 7 GB, 8 GB	Linux, Windows
2048 (2 vCPU)	Between 4 GB and 16 GB in 1 GB increments	Linux, Windows
4096 (4 vCPU)	Between 8 GB and 30 GB in 1 GB increments	Linux, Windows
8192 (8 vCPU) Note This option requires Linux platform 1.4.0 or later.	Between 16 GB and 60 GB in 4 GB increments	Linux
16384 (16vCPU) Note This option requires Linux platform 1.4.0 or later.	Between 32 GB and 120 GB in 8 GB increments	Linux

Logging

Event logging

Amazon ECS logs the actions that it takes to EventBridge. You can use Amazon ECS events for EventBridge to receive near real-time notifications regarding the current state of your Amazon ECS clusters, services, and tasks. Additionally, you can automate actions to respond to these events. For more information, see Amazon ECS events and EventBridge.

Task lifecycle logging

Tasks that run on Fargate publish timestamps to track the task through the states of the task lifecycle. You can see the timestamps in the task details in the AWS Management Console and by describing the task in the AWS CLI and SDKs. For example, you can use the timestamps to evaluate how much time the task spent downloading the container images and decide if you should optimize the container image size, or use Seekable OCI indexes. For more information about container image practices, see Container images.

Application logging

Fargate task definitions support the awslogs, splunk and awsfirelens log drivers only for the log configuration. The following code shows a snippet of a task definition where the awslogs log driver is configured:

"logConfiguration": { 
   "logDriver": "awslogs",
   "options": { 
      "awslogs-group" : "/ecs/fargate-task-definition",
      "awslogs-region": "us-east-1",
      "awslogs-stream-prefix": "ecs"
}

For more information about how you can use the awslogs log driver in task definitions to send your container logs to CloudWatch Logs, see Using the awslogs log driver.

For more information about using the awsfirelens log driver in a task definition, see Custom log routing.

Amazon ECS Task execution IAM role

You can specify an optional task execution IAM role with Fargate to allow your Fargate tasks to make API calls to Amazon ECR. The API calls pull container images. They also call CloudWatch to store container application logs. For more information, see Amazon ECS task execution IAM role.

Task storage

For Amazon ECS tasks on Fargate, the following storage types are supported:

• Amazon EFS volumes for persistent storage. For more information, see Amazon EFS volumes.

• Ephemeral storage for nonpersistent storage.

When provisioned, each Amazon ECS task hosted on Fargate receives the following ephemeral storage. The ephemeral storage configuration depends on which platform version the task is using. After a Fargate task stops, the ephemeral storage is deleted. For more information about Amazon ECS default service limits, see Amazon ECS service quotas.

Note

The host and sourcePath parameters are not supported for Fargate tasks.

Fargate Linux platform versions

Fargate tasks using platform version 1.4.0 or later

All Amazon ECS on Fargate tasks using platform version 1.4.0 or later receive a minimum of 20 GiB of ephemeral storage. Both the pulled, compressed, and the uncompressed container image for the task is stored on the ephemeral storage. To determine the total amount of ephemeral storage your task has to use, you must subtract the amount of storage your container image uses from the total amount.

For tasks using platform version 1.4.0 or later that are launched on May 28, 2020 or later, the ephemeral storage is encrypted with an AES-256 encryption algorithm using an AWS Fargate-managed encryption key.

Fargate tasks using platform version 1.3.0 or earlier

For Amazon ECS on Fargate tasks using platform version 1.3.0 or earlier, each task receives the following ephemeral storage.

• 10 GB of Docker layer storage

  Note

  This amount includes both compressed and uncompressed container image artifacts.

• An additional 4 GB for volume mounts. This can be mounted and shared among containers using the volumes, mountPoints and volumesFrom parameters in the task definition.

Fargate Windows platform versions

Fargate tasks using platform version 1.0.0 or later

All Amazon ECS on Fargate tasks using platform version 1.0.0 or later receive a minimum of 20 GiB of ephemeral storage. Both the pulled, compressed, and the uncompressed container image for the task is stored on the ephemeral storage. To determine the total amount of ephemeral storage your task has to use, you must subtract the amount of storage your container image uses from the total amount.

Example task definition

In this example, you have two application containers that need to access the same scratch file storage location.

To provide nonpersistent empty storage for containers in a Fargate task

1. In the task definition volumes section, define a volume with the name application_scratch.

     "volumes": [
       {
         "name": "application_scratch",
         "host": {}
       }
     ]

2. In the containerDefinitions section, create the application container definitions so they mount the nonpersistent storage.

     "containerDefinitions": [
       {
         "name": "application1",
         "image": "my-repo/application",
         "cpu": 100,
         "memory": 100,
         "essential": true,
         "mountPoints": [
           {
             "sourceVolume": "application_scratch",
             "containerPath": "/var/scratch"
           }
         ]
       },
       {
         "name": "application2",
         "image": "my-repo/application",
         "cpu": 100,
         "memory": 100,
         "essential": true,
         "mountPoints": [
           {
             "sourceVolume": "application_scratch",
             "containerPath": "/var/scratch"
           }
         ]
       }
     ]