diff --git a/contrib/completion/bash/docker b/contrib/completion/bash/docker index c04326036a..6055ede511 100644 --- a/contrib/completion/bash/docker +++ b/contrib/completion/bash/docker @@ -1151,6 +1151,7 @@ _docker_run() { --memory -m --memory-swap --memory-swappiness + --memory-reservation --name --net --pid diff --git a/docs/reference/commandline/create.md b/docs/reference/commandline/create.md index ba8b33a387..34ae6dfef7 100644 --- a/docs/reference/commandline/create.md +++ b/docs/reference/commandline/create.md @@ -50,6 +50,7 @@ Creates a new container. --lxc-conf=[] Add custom lxc options -m, --memory="" Memory limit --mac-address="" Container MAC address (e.g. 92:d0:c6:0a:29:33) + --memory-reservation="" Memory soft limit --memory-swap="" Total memory (memory + swap), '-1' to disable swap --memory-swappiness="" Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. --name="" Assign a name to the container diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 313f61558b..766ca205dc 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -50,6 +50,7 @@ weight=1 --lxc-conf=[] Add custom lxc options -m, --memory="" Memory limit --mac-address="" Container MAC address (e.g. 92:d0:c6:0a:29:33) + --memory-reservation="" Memory soft limit --memory-swap="" Total memory (memory + swap), '-1' to disable swap --memory-swappiness="" Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. --name="" Assign a name to the container diff --git a/docs/reference/run.md b/docs/reference/run.md index 6e109341f2..46dec11115 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -544,6 +544,7 @@ container: |----------------------------|---------------------------------------------------------------------------------------------| | `-m`, `--memory="" ` | Memory limit (format: `[]`, where unit = b, k, m or g) | | `--memory-swap=""` | Total memory limit (memory + swap, format: `[]`, where unit = b, k, m or g) | +| `--memory-reservation=""` | Memory soft limit (format: `[]`, where unit = b, k, m or g) | | `--kernel-memory=""` | Kernel memory limit (format: `[]`, where unit = b, k, m or g) | | `-c`, `--cpu-shares=0` | CPU shares (relative weight) | | `--cpu-period=0` | Limit the CPU CFS (Completely Fair Scheduler) period | @@ -629,6 +630,43 @@ would be 2*300M, so processes can use 300M swap memory as well. We set both memory and swap memory, so the processes in the container can use 300M memory and 700M swap memory. +Memory reservation is a kind of memory soft limit that allows for greater +sharing of memory. Under normal circumstances, containers can use as much of +the memory as needed and are constrained only by the hard limits set with the +`-m`/`--memory` option. When memory reservation is set, Docker detects memory +contention or low memory and forces containers to restrict their consumption to +a reservation limit. + +Always set the memory reservation value below the hard limit, otherwise the hard +limit takes precedence. A reservation of 0 is the same as setting no +reservation. By default (without reservation set), memory reservation is the +same as the hard memory limit. + +Memory reservation is a soft-limit feature and does not guarantee the limit +won't be exceeded. Instead, the feature attempts to ensure that, when memory is +heavily contended for, memory is allocated based on the reservation hints/setup. + +The following example limits the memory (`-m`) to 500M and sets the memory +reservation to 200M. + +```bash +$ docker run -ti -m 500M --memory-reservation 200M ubuntu:14.04 /bin/bash +``` + +Under this configuration, when the container consumes memory more than 200M and +less than 500M, the next system memory reclaim attempts to shrink container +memory below 200M. + +The following example set memory reservation to 1G without a hard memory limit. + +```bash +$ docker run -ti --memory-reservation 1G ubuntu:14.04 /bin/bash +``` + +The container can use as much memory as it needs. The memory reservation setting +ensures the container doesn't consume too much memory for long time, because +every memory reclaim shrinks the container's consumption to the reservation. + By default, kernel kills processes in a container if an out-of-memory (OOM) error occurs. To change this behaviour, use the `--oom-kill-disable` option. Only disable the OOM killer on containers where you have also set the diff --git a/man/docker-create.1.md b/man/docker-create.1.md index e82ac3381c..e845befe97 100644 --- a/man/docker-create.1.md +++ b/man/docker-create.1.md @@ -40,6 +40,7 @@ docker-create - Create a new container [**--lxc-conf**[=*[]*]] [**-m**|**--memory**[=*MEMORY*]] [**--mac-address**[=*MAC-ADDRESS*]] +[**--memory-reservation**[=*MEMORY-RESERVATION*]] [**--memory-swap**[=*MEMORY-SWAP*]] [**--memory-swappiness**[=*MEMORY-SWAPPINESS*]] [**--name**[=*NAME*]] @@ -196,6 +197,15 @@ system's page size (the value would be very large, that's millions of trillions) **--mac-address**="" Container MAC address (e.g. 92:d0:c6:0a:29:33) +**--memory-reservation**="" + Memory soft limit (format: [], where unit = b, k, m or g) + + After setting memory reservation, when the system detects memory contention +or low memory, containers are forced to restrict their consumption to their +reservation. So you should always set the value below **--memory**, otherwise the +hard limit will take precedence. By default, memory reservation will be the same +as memory limit. + **--memory-swap**="" Total memory limit (memory + swap) diff --git a/man/docker-run.1.md b/man/docker-run.1.md index ebb65d71c7..960ac9f27d 100644 --- a/man/docker-run.1.md +++ b/man/docker-run.1.md @@ -41,6 +41,7 @@ docker-run - Run a command in a new container [**--lxc-conf**[=*[]*]] [**-m**|**--memory**[=*MEMORY*]] [**--mac-address**[=*MAC-ADDRESS*]] +[**--memory-reservation**[=*MEMORY-RESERVATION*]] [**--memory-swap**[=*MEMORY-SWAP*]] [**--memory-swappiness**[=*MEMORY-SWAPPINESS*]] [**--name**[=*NAME*]] @@ -290,6 +291,15 @@ RAM. If a limit of 0 is specified (not using **-m**), the container's memory is not limited. The actual limit may be rounded up to a multiple of the operating system's page size (the value would be very large, that's millions of trillions). +**--memory-reservation**="" + Memory soft limit (format: [], where unit = b, k, m or g) + + After setting memory reservation, when the system detects memory contention +or low memory, containers are forced to restrict their consumption to their +reservation. So you should always set the value below **--memory**, otherwise the +hard limit will take precedence. By default, memory reservation will be the same +as memory limit. + **--memory-swap**="" Total memory limit (memory + swap)