Task definition considerations - Amazon ECS

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 Fargate tasks:

  • devices

  • disableNetworking

  • dnsSearchDomains

  • dnsServers

  • dockerSecurityOptions

  • dockerVolumeConfiguration

  • extraHosts

  • host

  • hostname

  • links

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

  • privileged

  • sharedMemorySize

  • tmpfs


When any one of the task definition parameters isn't supported, it is assumed that any subflags for that parameter 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.

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

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

  • If you use the portMappings parameter, you should only specify the containerPort. The hostPort can either be left blank or be set to the same value as the containerPort.

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

Fargate task definitions require that you specify CPU and memory at the task level. Even though you can also specify CPU and memory at the container level for Fargate tasks, this is optional. Most use cases are satisfied by only specifying these resources at the task level. The following table shows the valid combinations of task-level CPU and memory.

CPU value

Memory value

256 (.25 vCPU)

0.5 GB, 1 GB, 2 GB

512 (.5 vCPU)

1 GB, 2 GB, 3 GB, 4 GB

1024 (1 vCPU)

2 GB, 3 GB, 4 GB, 5 GB, 6 GB, 7 GB, 8 GB

2048 (2 vCPU)

Between 4 GB and 16 GB in 1-GB increments

4096 (4 vCPU)

Between 8 GB and 30 GB in 1-GB increments


Fargate task definitions only support the awslogs, splunk and awsfirelens log drivers 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

There is an optional task execution IAM role that you can specify with Fargate to allow your Fargate tasks to make API calls to Amazon ECR. The API calls pull container images as well as call CloudWatch to store container application logs. For more information, see Amazon ECS task execution IAM role.

Example task definition

The following is an example task definition that uses the Fargate launch type to set up a web server:

{ "containerDefinitions": [ { "command": [ "/bin/sh -c \"echo '<html> <head> <title>Amazon ECS Sample App</title> <style>body {margin-top: 40px; background-color: #333;} </style> </head><body> <div style=color:white;text-align:center> <h1>Amazon ECS Sample App</h1> <h2>Congratulations!</h2> <p>Your application is now running on a container in Amazon ECS.</p> </div></body></html>' > /usr/local/apache2/htdocs/index.html && httpd-foreground\"" ], "entryPoint": [ "sh", "-c" ], "essential": true, "image": "httpd:2.4", "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group" : "/ecs/fargate-task-definition", "awslogs-region": "us-east-1", "awslogs-stream-prefix": "ecs" } }, "name": "sample-fargate-app", "portMappings": [ { "containerPort": 80, "hostPort": 80, "protocol": "tcp" } ] } ], "cpu": "256", "executionRoleArn": "arn:aws:iam::012345678910:role/ecsTaskExecutionRole", "family": "fargate-task-definition", "memory": "512", "networkMode": "awsvpc", "requiresCompatibilities": [ "FARGATE" ] }

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.


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

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


    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.

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" } ] } ]