Task Definition Considerations - Amazon ECS

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 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 is not supported.

  • The healthCheck parameter is only supported for Fargate tasks using 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. 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, splunk and awsfirelens log drivers for the log configuration. 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.

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

For Fargate tasks, 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 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.

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 20 GB of ephemeral storage.

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

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

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