mirror of https://github.com/docker/docs.git
Clarify how to stop a container from using swap (#4409)
This commit is contained in:
Misty Stanley-Jones
GitHub
parent
3638cfa266
commit
9aa87cd0a0
|
|
@ -44,7 +44,7 @@ You can mitigate the risk of system instability due to OOME by:
|
|||
- Limit the amount of memory your container can use, as described below.
|
||||
- Be mindful when configuring swap on your Docker hosts. Swap is slower and
|
||||
less performant than memory but can provide a buffer against running out of
|
||||
system memory.
|
||||
system memory.
|
||||
- Consider converting your container to a [service](/engine/swarm/services.md),
|
||||
and using service-level constraints and node labels to ensure that the
|
||||
application runs only on hosts with enough memory
|
||||
|
|
@ -61,14 +61,14 @@ one option is set.
|
|||
Most of these options take a positive integer, followed by a suffix of `b`, `k`,
|
||||
`m`, `g`, to indicate bytes, kilobytes, megabytes, or gigabytes.
|
||||
|
||||
| Option | Description |
|
||||
|-----------------------|-----------------------------|
|
||||
| `-m` or `--memory=` | The maximum amount of memory the container can use. If you set this option, the minimum allowed value is `4m` (4 megabyte). |
|
||||
| `--memory-swap`* | The amount of memory this container is allowed to swap to disk. See [`--memory-swap` details](resource_constraints.md#--memory-swap-details). |
|
||||
| `--memory-swappiness` | By default, the host kernel can swap out a percentage of anonymous pages used by a container. You can set `--memory-swappiness` to a value between 0 and 100, to tune this percentage. See [`--memory-swappiness` details](resource_constraints.md#--memory-swappiness-details). |
|
||||
| `--memory-reservation` | Allows you to specify a soft limit smaller than `--memory` which is activated when Docker detects contention or low memory on the host machine. If you use `--memory-reservation`, it must be set lower than `--memory` in order for it to take precedence. Because it is a soft limit, it does not guarantee that the container will not exceed the limit. |
|
||||
| `--kernel-memory` | The maximum amount of kernel memory the container can use. The minimum allowed value is `4m`. Because kernel memory cannot be swapped out, a container which is starved of kernel memory may block host machine resources, which can have side effects on the host machine and on other containers. See [`--kernel-memory` details](resource_constraints.md#--kernel-memory-details). |
|
||||
| `--oom-kill-disable` | By default, if an out-of-memory (OOM) error occurs, the kernel kills processes in a container. To change this behavior, use the `--oom-kill-disable` option. Only disable the OOM killer on containers where you have also set the `-m/--memory` option. If the `-m` flag is not set, the host can run out of memory and the kernel may need to kill the host system's processes to free memory. |
|
||||
| Option | Description |
|
||||
|:-----------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `-m` or `--memory=` | The maximum amount of memory the container can use. If you set this option, the minimum allowed value is `4m` (4 megabyte). |
|
||||
| `--memory-swap`* | The amount of memory this container is allowed to swap to disk. See [`--memory-swap` details](resource_constraints.md#--memory-swap-details). |
|
||||
| `--memory-swappiness` | By default, the host kernel can swap out a percentage of anonymous pages used by a container. You can set `--memory-swappiness` to a value between 0 and 100, to tune this percentage. See [`--memory-swappiness` details](resource_constraints.md#--memory-swappiness-details). |
|
||||
| `--memory-reservation` | Allows you to specify a soft limit smaller than `--memory` which is activated when Docker detects contention or low memory on the host machine. If you use `--memory-reservation`, it must be set lower than `--memory` in order for it to take precedence. Because it is a soft limit, it does not guarantee that the container will not exceed the limit. |
|
||||
| `--kernel-memory` | The maximum amount of kernel memory the container can use. The minimum allowed value is `4m`. Because kernel memory cannot be swapped out, a container which is starved of kernel memory may block host machine resources, which can have side effects on the host machine and on other containers. See [`--kernel-memory` details](resource_constraints.md#--kernel-memory-details). |
|
||||
| `--oom-kill-disable` | By default, if an out-of-memory (OOM) error occurs, the kernel kills processes in a container. To change this behavior, use the `--oom-kill-disable` option. Only disable the OOM killer on containers where you have also set the `-m/--memory` option. If the `-m` flag is not set, the host can run out of memory and the kernel may need to kill the host system's processes to free memory. |
|
||||
|
||||
For more information about cgroups and memory in general, see the documentation
|
||||
for [Memory Resource Controller](https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt).
|
||||
|
|
@ -92,8 +92,9 @@ Its setting can have complicated effects:
|
|||
treated as unset.
|
||||
|
||||
- If `--memory-swap` is set to the same value as `--memory`, and `--memory` is
|
||||
set to a positive integer, the effect is the same as setting `--memory-swap`
|
||||
to `0` (the value is treated as unset).
|
||||
set to a positive integer, **the container will not have access to swap**.
|
||||
See
|
||||
[Prevent a container from using swap](#prevent-a-container-from-using-swap).
|
||||
|
||||
- If `--memory-swap` is unset, and `--memory` is set, the container can use
|
||||
twice as much swap as the `--memory` setting, if the host container has swap
|
||||
|
|
@ -103,6 +104,13 @@ Its setting can have complicated effects:
|
|||
- If `--memory-swap` is explicitly set to `-1`, the container is allowed to use
|
||||
unlimited swap, up to the amount available on the host system.
|
||||
|
||||
#### Prevent a container from using swap
|
||||
|
||||
If `--memory` and `--memory-swap` are set to the same value, this will prevent
|
||||
containers from using any swap. This is because `--memory-swap` is the amount of
|
||||
combined memory and swap that can be used, while `--memory` is only the amount
|
||||
of physical memory that can be used.
|
||||
|
||||
### `--memory-swappiness` details
|
||||
|
||||
- A value of 0 turns off anonymous page swapping.
|
||||
|
|
@ -154,13 +162,13 @@ runtime flags allow you to configure the amount of access to CPU resources your
|
|||
container has. When you use these settings, Docker modifies the settings for
|
||||
the container's cgroup on the host machine.
|
||||
|
||||
| Option | Description |
|
||||
|-----------------------|-----------------------------|
|
||||
| `--cpus=<value>` | Specify how much of the available CPU resources a container can use. For instance, if the host machine has two CPUs and you set `--cpus="1.5"`, the container will be guaranteed to be able to access at most one and a half of the CPUs. This is the equivalent of setting `--cpu-period="100000"` and `--cpu-quota="150000"`. Available in Docker 1.13 and higher. |
|
||||
| `--cpu-period=<value>`| Specify the CPU CFS scheduler period, which is used alongside `--cpu-quota`. Defaults to 1 second, expressed in micro-seconds. Most users do not change this from the default. If you use Docker 1.13 or higher, use `--cpus` instead. |
|
||||
| `--cpu-quota=<value>` | Impose a CPU CFS quota on the container. The number of microseconds per `--cpu-period` that the container is guaranteed CPU access. In other words, `cpu-quota / cpu-period`. If you use Docker 1.13 or higher, use `--cpus` instead. |
|
||||
| `--cpuset-cpus` | Limit the specific CPUs or cores a container can use. A comma-separated list or hyphen-separated range of CPUs a container can use, if you have more than one CPU. The first CPU is numbered 0. A valid value might be `0-3` (to use the first, second, third, and fourth CPU) or `1,3` (to use the second and fourth CPU). |
|
||||
| `--cpu-shares` | Set this flag to a value greater or less than the default of 1024 to increase or reduce the container's weight, and give it access to a greater or lesser proportion of the host machine's CPU cycles. This is only enforced when CPU cycles are constrained. When plenty of CPU cycles are available, all containers use as much CPU as they need. In that way, this is a soft limit. `--cpu-shares` does not prevent containers from being scheduled in swarm mode. It prioritizes container CPU resources for the available CPU cycles. It does not guarantee or reserve any specific CPU access. |
|
||||
| Option | Description |
|
||||
|:-----------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `--cpus=<value>` | Specify how much of the available CPU resources a container can use. For instance, if the host machine has two CPUs and you set `--cpus="1.5"`, the container will be guaranteed to be able to access at most one and a half of the CPUs. This is the equivalent of setting `--cpu-period="100000"` and `--cpu-quota="150000"`. Available in Docker 1.13 and higher. |
|
||||
| `--cpu-period=<value>` | Specify the CPU CFS scheduler period, which is used alongside `--cpu-quota`. Defaults to 1 second, expressed in micro-seconds. Most users do not change this from the default. If you use Docker 1.13 or higher, use `--cpus` instead. |
|
||||
| `--cpu-quota=<value>` | Impose a CPU CFS quota on the container. The number of microseconds per `--cpu-period` that the container is guaranteed CPU access. In other words, `cpu-quota / cpu-period`. If you use Docker 1.13 or higher, use `--cpus` instead. |
|
||||
| `--cpuset-cpus` | Limit the specific CPUs or cores a container can use. A comma-separated list or hyphen-separated range of CPUs a container can use, if you have more than one CPU. The first CPU is numbered 0. A valid value might be `0-3` (to use the first, second, third, and fourth CPU) or `1,3` (to use the second and fourth CPU). |
|
||||
| `--cpu-shares` | Set this flag to a value greater or less than the default of 1024 to increase or reduce the container's weight, and give it access to a greater or lesser proportion of the host machine's CPU cycles. This is only enforced when CPU cycles are constrained. When plenty of CPU cycles are available, all containers use as much CPU as they need. In that way, this is a soft limit. `--cpu-shares` does not prevent containers from being scheduled in swarm mode. It prioritizes container CPU resources for the available CPU cycles. It does not guarantee or reserve any specific CPU access. |
|
||||
|
||||
If you have 1 CPU, each of the following commands will guarantee the container at
|
||||
most 50% of the CPU every second.
|
||||
|
|
@ -217,11 +225,11 @@ You can pass several flags to control a container's CPU priority when you
|
|||
start the container using `docker run`. Consult your operating system's
|
||||
documentation or the `ulimit` command for information on appropriate values.
|
||||
|
||||
| Option | Description |
|
||||
|---------------------------|-----------------------------|
|
||||
| `--cap-add=sys_nice` | Grants the container the `CAP_SYS_NICE` capability, which allows the container to raise process `nice` values, set real-time scheduling policies, set CPU affinity, and other operations. |
|
||||
| `--cpu-rt-runtime=<value>`| The maximum number of microseconds the container can run at realtime priority within the Docker daemon's realtime scheduler period. You also need the `--cap-add=sys_nice` flag. |
|
||||
| `--ulimit rtprio=<value>` | The maximum realtime priority allowed for the container. You also need the `--cap-add=sys_nice` flag. |
|
||||
| Option | Description |
|
||||
|:---------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `--cap-add=sys_nice` | Grants the container the `CAP_SYS_NICE` capability, which allows the container to raise process `nice` values, set real-time scheduling policies, set CPU affinity, and other operations. |
|
||||
| `--cpu-rt-runtime=<value>` | The maximum number of microseconds the container can run at realtime priority within the Docker daemon's realtime scheduler period. You also need the `--cap-add=sys_nice` flag. |
|
||||
| `--ulimit rtprio=<value>` | The maximum realtime priority allowed for the container. You also need the `--cap-add=sys_nice` flag. |
|
||||
|
||||
The following example command sets each of these three flags on a `debian:jessie`
|
||||
container.
|
||||
|
|
|
|||
Loading…
Reference in New Issue