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

Short description

When you create a task definition in Amazon ECS, you can define limits for CPU resources at the task-level and the container level. These limits can affect the overall performance of your Amazon ECS cluster. Depending on the Amazon ECS behaviors and your use case, 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.

Resolution

Amazon ECS uses a standard unit of measure for CPU resources called CPU units. For example, 1024 CPU units are the equivalent of 1 vCPU for Linux, and 2048 CPU units is equal to 2 vCPU. When you define task definitions, you can use 1 vCPU instead of 1024. When the task definition is registered, ECS translates the value into units.

Note: Task-level CPU and memory parameters are ignored for Windows containers. For Windows containers, it's a best practice to specify container-level resources. For more information, see Task size.

Task-level CPU allocation

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

For Linux instances, the cpu parameter that you set at the task-level also sets the maximum CPU resources allowed for tasks in that container. The containers that run in this task configuration can use only the cpu capacity defined by the task size.

AWS Fargate

For Linux and Windows, 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.

Amazon EC2

Note: For tasks that run on Amazon EC2 Linux, the cpu parameter is optional.

If you define the cpu parameter in Linux, then the parameter has the following limits:

• Your containers have limited access based on the amount of cpu that you define at the task level.
• The value that you define in your Task cpu parameter becomes the CPU reservation for the task scheduled on a container instance.
• cpu units assigned to containers use Linux CPU shares to implement the shares within the task. Linux CPU is a weighted mechanism to determine CPU access priority.

In the following example, a cpu parameter has the following definition on Amazon EC2:

• 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 defined in task-level definitions is running on the instance.
• Current instance EC2 CPUUtilization is at 68%.

In the preceding example, the configuration has 1024 CPU units left in its pool.

The current CPUUtilization doesn't affect how many CPU Units are available in the container instance to schedule tasks. If the instance exceeds 50% of its utilization, then half of the units in the instance pool are available for new tasks to start. The parameter acts as a CPU reservation and limit, and the parameter doesn't directly translate to CPU usage.

With the preceding example parameters, you have several configurations that you can make if you account only for the CPU:

• 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. You can set these levels in each of the two containers.
• 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 at scheduling time and at runtime when there's no CPU contention.

At Scheduling time

The following container-level cpu definitions are considered at the scheduling time:

• When the task-level cpu definition isn't set, then the total number 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 when there's no CPU contention

The following container-level cpu definitions are considered at runtime when there's 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. The containers can access the resources regardless of the cpu definition set at the container level.
• If you use Windows and the cpu at task level isn't supported, then the containers are capped at the container level cpu definition.

Note: On Windows container instances, the CPU quota is enforced as an absolute quota. For more information, see Environment.

For Linux container instances, Container-level cpu definitions are directly mapped to the CpuShares parameters. For more information, see Create a container API on the Docker website.

CPU contention

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

Important: Verify that the application that you run 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. These applications use the container-level definition even if there's CPU contention.

Related information

How can I allocate memory to tasks in Amazon ECS?