Amazon ECS task definition differences for the Fargate launch type - Amazon Elastic Container Service
Task definition parametersOperating Systems and architecturesTask CPU and memoryTask networkingTask resource limitsLoggingTask storageLazy loading SOCI container images

Amazon ECS task definition differences for the Fargate launch type

In order to use Fargate, you must configure your task definion to use the Fargate launch type. There are additional considerations when using Fargate.

Task definition parameters

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 are not valid in Fargate tasks:

  • disableNetworking

  • dnsSearchDomains

  • dnsServers

  • dockerSecurityOptions

  • extraHosts

  • gpu

  • ipcMode

  • links

  • placementConstraints

  • privileged

  • maxSwap

  • swappiness

The following task definition parameters are valid in Fargate tasks, but have limitations that should be noted:

  • linuxParameters – When specifying Linux-specific options that are applied to the container, for capabilities the only capability you can add is CAP_SYS_PTRACE. The devices, sharedMemorySize, and tmpfs parameters are not supported. For more information, see Linux parameters.

  • volumes – Fargate tasks only support bind mount host volumes, so the dockerVolumeConfiguration parameter is not supported. For more information, see Volumes.

  • cpu - For Windows containers on AWS Fargate, the value cannot be less than 1 vCPU.

  • networkConfiguration - Fargate tasks always use the awsvpc netwok mode.

To ensure that your task definition validates for use with Fargate, 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, specify the --requires-compatibilities option.

  • In the Amazon ECS API, specify the requiresCompatibilities flag.

Operating Systems and architectures

When you configure a task and container definition for AWS Fargate, you must specify the Operating System that the container runs. The following Operating Systems are supported for AWS Fargate:

  • Amazon Linux 2

    Note

    Linux containers use only the kernel and kernel configuration from the host Operating System. For example, the kernel configuration includes the sysctl system controls. A Linux container image can be made from a base image that contains the files and programs from any Linux distribution. If the CPU architecture matches, you can run containers from any Linux container image on any Operating System.

  • Windows Server 2019 Full

  • Windows Server 2019 Core

  • Windows Server 2022 Full

  • Windows Server 2022 Core

When you run Windows containers on AWS Fargate, you must have the X86_64 CPU architecture.

When you run Linux containers on AWS Fargate, you can use the X86_64 CPU architecture, or the ARM64 architecture for your ARM-based applications. For more information, see Amazon ECS task definitions for 64-bit ARM workloads.

Task CPU and memory

Amazon ECS task definitions for AWS Fargate 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. You can specify memory values in the task definition as a string in MiB or GB. For example, you can specify a memory value either as 3072 in MiB or 3 GB in GB. You can specify CPU values in the JSON file as a string in CPU units or virtual CPUs (vCPUs). For example, you can specify a CPU value either as 1024 in CPU units or 1 vCPU in vCPUs.

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

Task networking

Amazon ECS tasks for AWS Fargate require the awsvpc network mode, which provides each task with an elastic network interface. When you run a task or create a service with this network mode, you must specify one or more subnets to attach the network interface and one or more security groups to apply to the network interface.

If you are using public subnets, decide whether to provide a public IP address for the network interface. For a Fargate task in a public subnet to pull container images, a public IP address needs to be assigned to the task's elastic network interface, with a route to the internet or a NAT gateway that can route requests to the internet. For a Fargate task in a private subnet to pull container images, you need a NAT gateway in the subnet to route requests to the internet. When you host your container images in Amazon ECR, you can configure Amazon ECR to use an interface VPC endpoint. In this case, the task's private IPv4 address is used for the image pull. For more information about Amazon ECR interface endpoints, see Amazon ECR interface VPC endpoints (AWS PrivateLink) in the Amazon Elastic Container Registry User Guide.

The following is an example of the networkConfiguration section for a Fargate service:

"networkConfiguration": { 
   "awsvpcConfiguration": { 
      "assignPublicIp": "ENABLED",
      "securityGroups": [ "sg-12345678" ],
      "subnets": [ "subnet-12345678" ]
   }
}

Task resource limits

Amazon ECS task definitions for Linux containers on AWS Fargate support the ulimits parameter to define the resource limits to set for a container.

Amazon ECS task definitions for Windows on AWS Fargate do not support the ulimits parameter to define the resource limits to set for a container.

Amazon ECS tasks hosted on Fargate use the default resource limit values set by the operating system with the exception of the nofile resource limit parameter. The nofile resource limit sets a restriction on the number of open files that a container can use. On Fargate, the default nofile soft limit is 65535 and hard limit is 65535. You can set the values of both limits up to 1048576.

The following is an example task definition snippet that shows how to define a custom nofile limit that has been doubled:

"ulimits": [
    {
       "name": "nofile",
       "softLimit": 2048,
       "hardLimit": 8192
    }
]

For more information on the other resource limits that can be adjusted, see Resource limits.

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 Automate responses to Amazon ECS errors using 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 Best practices for Amazon ECS container images.

Application logging

Amazon ECS task definitions for AWS Fargate support the awslogs, splunk, and awsfirelens log drivers for the log configuration.

The awslogs log driver 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 a task definition to send your container logs to CloudWatch Logs, see Send Amazon ECS logs to CloudWatch .

For more information about the awsfirelens log driver in a task definition, see Send Amazon ECS logs to an AWS service or AWS Partner.

For more information about using the splunk log driver in a task definition, see splunk log driver.

Task storage

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

Lazy loading container images using Seekable OCI (SOCI)

Amazon ECS tasks on Fargate that use Linux platform version 1.4.0 can use Seekable OCI (SOCI) to help start tasks faster. With SOCI, containers only spend a few seconds on the image pull before they can start, providing time for environment setup and application instantiation while the image is downloaded in the background. This is called lazy loading. When Fargate starts an Amazon ECS task, Fargate automatically detects if a SOCI index exists for an image in the task and starts the container without waiting for the entire image to be downloaded.

For containers that run without SOCI indexes, container images are downloaded completely before the container is started. This behavior is the same on all other platform versions of Fargate and on the Amazon ECS-optimized AMI on Amazon EC2 instances.

Seekable OCI indexes

Seekable OCI (SOCI) is an open source technology developed by AWS that can launch containers faster by lazily loading the container image. SOCI works by creating an index (SOCI Index) of the files within an existing container image. This index helps to launch containers faster, providing the capability to extract an individual file from a container image before downloading the entire image. The SOCI index must be stored as an artifact in the same repository as the image within the container registry. You should only use SOCI indices from trusted sources, as the index is the authoritative source for the contents of the image. For more information, see Introducing Seekable OCI for lazy loading container images.

Considerations

If you want Fargate to use a SOCI index to lazily load container images in a task, consider the following:

  • Only tasks that run on Linux platform version 1.4.0 can use SOCI indexes. Tasks that run Windows containers on Fargate aren't supported.

  • Tasks that run on X86_64 or ARM64 CPU architecture are supported.

  • Container images in the task definition must have SOCI indexes in the same container registry as the image.

  • Container images in the task definition must be stored in a compatible image registry. The following lists the compatible registries:

    • Amazon ECR private registries.

  • Only container images that use gzip compression or are not compressed are supported. Container images that use zstd compression aren't supported.

  • We recommend that you try lazy loading with container images greater than 250 MiB compressed in size. You are less likely to see a reduction in the time to load smaller images.

  • Because lazy loading can change how long your tasks take to start, you might need to change various timeouts like the health check grace period for Elastic Load Balancing.

  • If you want to prevent a container image from being lazy loaded, delete the SOCI index from the container registry. If a container image in the task doesn't meet one of the considerations, that container image is downloaded by the default method.

Creating a Seekable OCI index

For a container image to be lazy loaded it needs a SOCI index (a metadata file) created and stored in the container image repository along side the container image. To create and push a SOCI index you can use the open source soci-snapshotter CLI tool on GitHub. Or, you can deploy the CloudFormation AWS SOCI Index Builder. This is a serverless solution that automatically creates and pushes a SOCI index when a container image is pushed to Amazon ECR. For more information about the solution and the installation steps, see CloudFormation AWS SOCI Index Builder on GitHub. The CloudFormation AWS SOCI Index Builder is a way to automate getting started with SOCI, while the open source soci tool has more flexibility around index generation and the ability to integrate index generation in your continuous integration and continuous delivery (CI/CD) pipelines.

Note

For the SOCI index to be created for an image, the image must exist in the containerd image store on the computer running soci-snapshotter. If the image is in the Docker image store, the image can't be found.

Verifying that a task used lazy loading

To verify that a task was lazily loaded using SOCI, check the task metadata endpoint from inside the task. When you query the task metadata endpoint version 4, there is a Snapshotter field in the default path for the container that you are querying from. Additionally, there are Snapshotter fields for each container in the /task path. The default value for this field is overlayfs, and this field is set to soci if SOCI is used. .