What do I need to know about CPU allocation in Amazon ECS?

5 minute read

I'm looking for information related to allocating CPU to tasks in Amazon Elastic Container Service (Amazon ECS).

Short description

When creating a task definition, you can define limits for CPU resources. These limits can be defined at the task-level and the container level.

The overall performance of your Amazon ECS cluster is affected based on these limits. Depending on the Amazon ECS behaviors and your use case, you must adjust the CPU allocation values at the task level and the container level. Use the following information to determine the CPU allocation that meets your workload and application requirements.


Amazon ECS uses a standard unit of measure for CPU resources called CPU units. 1024 CPU units is the equivalent of 1 vCPU.

For example, 2048 CPU units is equal to 2 vCPU.

Note: When defining task definitions, you can also use 1 vCPU instead of 1024. When the task definition is registered, ECS translates the value into units.

Task-level CPU allocation

Amazon ECS tasks can be run on AWS Fargate or Amazon Elastic Compute Cloud (Amazon EC2) instances.

When you set the cpu parameter on the task-level, you'll also be setting the maximum amount of CPU resources that your containers in a task are allowed.

AWS Fargate

AWS Fargate requires a cpu parameter on the task level to allocate requested resources to the task. You can select the memory and cpu from predefined task sizes available for AWS Fargate. You can learn more about the different combinations under the Task CPU and memory section of the AWS Fargate Developer Guide.

Amazon EC2

When running tasks on Amazon EC2, the cpu parameter is optional.

If you define the cpu parameter, consider the following:

  • Your containers will have limited access based on the amount of cpu defined.
  • The amount defined in your cpu parameter becomes the CPU reservation for the task to be scheduled on a container instance.
    Note: This is also true for the container-level definition.

For example, a defined cpu parameter on Amazon EC2 with the following configuration will have 1024 CPU units left in its pool:

  • An m5.large EC2 instance registered in an ECS cluster as a container instance for a total of 2048 CPU units.
  • One task with cpu: 1024 at task-level defined is running on the instance.
  • Current instance EC2 CPUUtilization is at 68%.

The current CPUUtilization doesn't affect how many CPU Units are available in the container instance for task scheduling. Even if the instance exceeds 50% of its utilization, you will still have half of the units in its pool available for new tasks to start. This is because the parameter acts only as a CPU reservation and limit and doesn't translate directly to CPU usage itself.

With this example, there are several results that can happen when taking only CPU into account:

  • You can schedule two more tasks with cpu: 512 defined in either task-level or container-level definitions.
  • You can schedule one task, with two containers, with cpu: 1024 defined at the task level and cpu: 512 defined at the container level in each container.
  • If the cpu isn't defined, then you can schedule as many tasks as ECS supports for the network mode that you selected. The CPU units available in your ECS container instance for scheduling aren't affected.

Container-level CPU allocation

Container-level cpu definitions are considered in the following scenarios:

At Scheduling time:

  • When the task-level cpu definition isn't set, then the total amount of CPU units defined in your containers becomes the CPU reservation.
  • The total number of CPU units in your cpu container-level definition can't be larger than the CPU units defined at your task-level allocation.

At Runtime, and there is no CPU contention:

  • If Task-level cpu definition is set, then your containers have access only to cpu resources up to the task-level cpu defined value.
  • If Task-level cpu definition isn't set, then the containers in your task have access to all the CPU resources available in your instance, regardless of the cpu definition set at the container level.
  • If you're using Windows tasks and the cpu at task level isn't supported, then the containers are always capped to the definition of cpu at the container level.

CPU contention happens when multiple processes are requesting cpu time. When CPU contention occurs, your containers are throttled to the amount of resources defined on your cpu at the container-level definition.

**Important:**Be sure to verify if the application you are running on ECS is container aware. Some applications, such as Java 10, are container aware, and use only the limits defined in the container-level cpu definition, regardless of whether there is CPU contention.

Container-level cpu definitions are mapped directly to the CpuShares parameters of the Create a Container remote docker API.

Related information

How can I allocate memory to tasks in Amazon ECS?

AWS OFFICIALUpdated 2 years ago