Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Fargate considerations for Amazon ECS

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:

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

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

Operating Systems and architectures

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

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

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

Task CPU and memory

Amazon ECS task definitions for Amazon 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 JSON file in MiB or GB. You can specify CPU values in the JSON file as an integer in CPU units or virtual CPUs (vCPUs).

Task networking

Amazon ECS tasks for Amazon 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 (Amazon 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 Amazon Fargate support the ulimits parameter to define the resource limits to set for a container.

Amazon ECS task definitions for Windows on Amazon 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 1024 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 Amazon Web Services Management Console and by describing the task in the Amazon 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 container images.

Application logging

Amazon ECS task definitions for Amazon 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 Using the awslogs log driver.

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

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

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 Amazon 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 Amazon SOCI Index Builder on GitHub. The CloudFormation Amazon 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.

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. For more information, see Task metadata endpoint version 4 in the Amazon Elastic Container Service User Guide for Amazon Fargate.