How can I allocate memory to tasks in Amazon ECS?

Short description

In Amazon ECS, you can define the memory of your task in 2 task definitions:

• Task size
• Container definitions

Amazon ECS calculates the service memory utilization metrics based on whether you use the memoryReservation or memory parameter. For more information, see Service level CPU and memory utilization.

In the following table, you can review the minimal options to configure for Amazon Elastic Compute Cloud (Amazon EC2) and AWS Fargate launch types:

	Task without Task Size	Task with a Task Size
Task CPU	Optional Config	Mandatory Config
Task Memory	Optional Config	Mandatory Config
Container CPU	Optional Config	Optional Config
Container Memory	Mandatory Config	Optional Config
Launch Type Compatibility	EC2 Only	EC2 and Fargate

For tasks that don't have a task size, you must configure the Container Memory for the task. You can use these tasks only for Amazon EC2 launch types. For tasks that have a defined task size, you can use the tasks for Amazon EC2 or AWS Fargate launch types. Then, configure the task memory and CPU. For more information, see Amazon ECS task definition parameters for the Fargate launch type.

Resolution

Review your container memory allocations

Complete the following steps:

1. Open the Amazon ECS console.
2. In the navigation pane, choose Clusters, and then select your cluster.
3. On the cluster details page, choose Infrastructure.
4. Under Container instances, select the container instance ID registered to your cluster.
5. Under Resources and networking, review the Memory details.

The memory parameter provides information about the following cluster details:

• Total capacity of memory available when the RegisterContainerInstance API call is made
• In-use memory that's allocated to ECS tasks that run on the instance
• Available memory that you can allocate to new tasks

Note: For statistics on the resource usage of the instance, use SSH or SSM to connect to the instance. Then, run the docker stats command. For more information, see docker container stats on the docker website.

For EC2 launch types, you must know the available memory on your container instances to correctly specify memory in your task definitions. If the memory specified in the task definition is greater than the memory available on the registered instance, then the task fails.

Use the Amazon ECS console JSON editor

To create an Amazon ECS task definition and allocate memory to tasks, you can use the Amazon ECS console JSON editor. For more information, see Procedure.

Use the Amazon ECS console

To use the Amazon ECS console to allocate memory to tasks, complete one of the following tasks.

Create a task definition with a soft limit (memoryReservation)

Complete the following steps:

1. Open the Amazon ECS console.
2. In the navigation pane, choose Task Definition, and then choose Create new task definition.
3. On the Create task definition screen, enter the following information:
   For Task definition family name, enter a name for your task.
   For Launch type, choose Amazon EC2 instances.
   Under the Container section, for Container details, enter the name and image URI for the container.
   For Resource allocation limits, enter a value for Memory soft limit. Then, choose Create.
   Note: The memory soft limit maps to the memoryReservation parameter.

Create a task definition with a hard limit (memory)

Complete the following steps:

1. Open the Amazon ECS console.
2. In the navigation pane, choose Task Definition, and then choose Create new task definition.
3. On the Create task definition screen, enter the following information:
   For Task definition family name, enter a name for your task.
   For Launch type, choose Amazon EC2 instances.
   Under the Container section, for Container details, enter the name and image URI for the container.
   For Resource allocation limits, enter a value for Memory hard limit. Then, choose Create.
   Note: The memory hard limit maps to the memory parameter.

Review your container's memory allocations

Complete the following steps:

1. Open the Amazon ECS console.
2. In the navigation pane, choose Clusters, and then select your cluster.
3. On the Cluster details page, choose the Infrastructure tab.
4. Select the container instance that's registered to the cluster.
5. On the Container instance tab, under Resources, review the Memory registered value.
   Note: When there are 0 tasks running, the Memory registered value equals the Memory available value.

Note: For statistics on the resource usage of the instance, use SSH or SSM to connect to the instance. Then, run the docker stats command. For more information, see docker container stats on the docker website.

For tasks that run as part of a service, the Service memory utilization metric reports usage as a percentage of the total memory resources. These resources are specified for the service in the task definition. For more information, see Service level CPU and memory utilization.

You can also use Container Insights for your cluster to see the MemoryUtilized metric. This metric shows the memory that tasks and containers are using.

Related information

How Amazon ECS manages CPU and memory resources

Managing container swap memory space on Amazon ECS

Creating an Amazon ECS cluster for the Amazon EC2 launch type

Reserving Amazon ECS Linux container instance memory

Resource Constraints on the Docker website