Amazon ECS
User Guide for AWS Fargate (API Version 2014-11-13)

Task Definition Considerations

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

The following task definition parameters are not 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

Important

When any task definition parameter is not supported, it is assumed that any subflags for that parameter are not supported either.

The following task definition parameters behave differently for Fargate tasks:

  • When using logConfiguration, the only supported logDriver for Fargate tasks is the awslogs log driver.

  • When using linuxParameters, for capabilities the drop parameter can be used but the add parameter is not supported.

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

  • If you use the ' 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 Task Networking with the awsvpc Network Mode.

Task CPU and Memory

Fargate task definitions require that you specify CPU and memory at the task level. Although 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 table below 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

Logging

Fargate task definitions only support the awslogs log driver for the log configuration. This configures your Fargate tasks to send log information to Amazon CloudWatch Logs. The following 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 using the awslogs log driver in task definitions to send your container logs to CloudWatch Logs, see Using the awslogs Log Driver.

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 using the Fargate launch type that sets 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

When provisioned, each Fargate task receives the following storage. Task storage is ephemeral. After a Fargate task stops, the storage is deleted.

  • 10 GB of Docker layer storage

  • 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.

    Note

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

For more information about Amazon ECS default service limits, see Amazon ECS Service Limits.

To provide nonpersistent empty storage for containers in a Fargate tasks

In this example, you may have two database containers that need to access the same scratch file storage location during a task.

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

    "volumes": [ { "name": "database_scratch", "host": {} } ]
  2. In the containerDefinitions section, create the database container definitions so they mount the nonpersistent storage.

    "containerDefinitions": [ { "name": "database1", "image": "my-repo/database", "cpu": 100, "memory": 100, "essential": true, "mountPoints": [ { "sourceVolume": "database_scratch", "containerPath": "/var/scratch" } ] }, { "name": "database2", "image": "my-repo/database", "cpu": 100, "memory": 100, "essential": true, "mountPoints": [ { "sourceVolume": "database_scratch", "containerPath": "/var/scratch" } ] } ]