Managing container swap space - Amazon Elastic Container Service
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.

Managing container swap space

With Amazon ECS, you can control the usage of swap memory space on your Linux container instances at the container level. Using a per-container swap configuration, each container within a task definition can have swap enabled or disabled. For those that have it enabled, the maximum amount of swap space that's used can be limited. For example, latency-critical containers can have swap disabled. In contrast, containers with high transient memory demands can have swap turned on to reduce the chances of out-of-memory errors when the container is under load.

The swap configuration for a container is managed by the following container definition parameters:


The total amount of swap memory (in MiB) a container can use. This parameter is translated to the --memory-swap option to docker run where the value is the sum of the container memory plus the maxSwap value.

If a maxSwap value of 0 is specified, the container doesn't use swap. Accepted values are 0 or any positive integer. If the maxSwap parameter is omitted, the container uses the swap configuration for the container instance that it's running on. A maxSwap value must be set for the swappiness parameter to be used.


You can use this to tune a container's memory swappiness behavior. A swappiness value of 0 causes swapping to not occur unless required. A swappiness value of 100 causes pages to be swapped aggressively. Accepted values are whole numbers between 0 and 100. If the swappiness parameter isn't specified, a default value of 60 is used. If a value isn't specified for maxSwap, this parameter is ignored. This parameter maps to the --memory-swappiness option to docker run.

In the following example, the JSON syntax is provided.

"containerDefinitions": [{ ... "linuxParameters": { "maxSwap": integer, "swappiness": integer }, ... }]

Container swap considerations

Consider the following when you use a per-container swap configuration.

  • Swap space must be enabled and allocated on the container instance for the containers to use.


    By default, the Amazon ECS optimized AMIs do not have swap enabled. You must enable swap on the instance to use this feature. For more information, see Instance Store Swap Volumes in the Amazon EC2 User Guide for Linux Instances or How do I allocate memory to work as swap space in an Amazon EC2 instance by using a swap file?.

  • The swap space container definition parameters are only supported for task definitions that use the EC2 launch type.

  • This feature is only supported for Linux containers.

  • If the maxSwap and swappiness container definition parameters are omitted from a task definition, each container has a default swappiness value of 60. Moreover, the total swap usage is limited to two times the memory reservation of the container.