diff --git a/contrib/completion/bash/docker b/contrib/completion/bash/docker index 0df25bf6e2..8de381d346 100644 --- a/contrib/completion/bash/docker +++ b/contrib/completion/bash/docker @@ -1075,6 +1075,7 @@ _docker_run() { --group-add --hostname -h --ipc + --kernel-memory --label-file --label -l --link diff --git a/docs/reference/commandline/create.md b/docs/reference/commandline/create.md index 8c093f18eb..fd7db14e6f 100644 --- a/docs/reference/commandline/create.md +++ b/docs/reference/commandline/create.md @@ -40,6 +40,7 @@ Creates a new container. --help=false Print usage -i, --interactive=false Keep STDIN open even if not attached --ipc="" IPC namespace to use + --kernel-memory="" Kernel memory limit -l, --label=[] Set metadata on the container (e.g., --label=com.example.key=value) --label-file=[] Read in a line delimited file of labels --link=[] Add link to another container diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index ab900d41b9..e563ab6382 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -40,6 +40,7 @@ weight=1 --help=false Print usage -i, --interactive=false Keep STDIN open even if not attached --ipc="" IPC namespace to use + --kernel-memory="" Kernel memory limit -l, --label=[] Set metadata on the container (e.g., --label=com.example.key=value) --label-file=[] Read in a file of labels (EOL delimited) --link=[] Add link to another container diff --git a/docs/reference/run.md b/docs/reference/run.md index f011e22879..036918901d 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -517,6 +517,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) | +| `--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 | | `--cpuset-cpus="" ` | CPUs in which to allow execution (0-3, 0,1) | @@ -526,9 +527,9 @@ container: | `--oom-kill-disable=false` | Whether to disable OOM Killer for the container or not. | | `--memory-swappiness="" ` | Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. | -### Memory constraints +### User memory constraints -We have four ways to set memory usage: +We have four ways to set user memory usage: @@ -576,7 +577,7 @@ We have four ways to set memory usage:
-### Examples +Examples: $ docker run -ti ubuntu:14.04 /bin/bash @@ -620,6 +621,76 @@ The following example, illustrates a dangerous way to use the flag: The container has unlimited memory which can cause the host to run out memory and require killing system processes to free memory. +### Kernel memory constraints + +Kernel memory is fundamentally different than user memory as kernel memory can't +be swapped out. The inability to swap makes it possible for the container to +block system services by consuming too much kernel memory. Kernel memory includes： + + - stack pages + - slab pages + - sockets memory pressure + - tcp memory pressure + +You can setup kernel memory limit to constrain these kinds of memory. For example, +every process consumes some stack pages. By limiting kernel memory, you can +prevent new processes from being created when the kernel memory usage is too high. + +Kernel memory is never completely independent of user memory. Instead, you limit +kernel memory in the context of the user memory limit. Assume "U" is the user memory +limit and "K" the kernel limit. There are three possible ways to set limits: + + + + + + + + + + + + + + + + + + + + + + +
OptionResult
U != 0, K = inf (default) + This is the standard memory limitation mechanism already present before using + kernel memory. Kernel memory is completely ignored. +
U != 0, K < U + Kernel memory is a subset of the user memory. This setup is useful in + deployments where the total amount of memory per-cgroup is overcommited. + Overcommiting kernel memory limits is definitely not recommended, since the + box can still run out of non-reclaimable memory. + In this case, the you can configure K so that the sum of all groups is + never greater than the total memory. Then, freely set U at the expense of + the system's service quality. +
U != 0, K > U + Since kernel memory charges are also fed to the user counter and reclaimation + is triggered for the container for both kinds of memory. This configuration + gives the admin a unified view of memory. It is also useful for people + who just want to track kernel memory usage. +
+ +Examples: + + $ docker run -ti -m 500M --kernel-memory 50M ubuntu:14.04 /bin/bash + +We set memory and kernel memory, so the processes in the container can use +500M memory in total, in this 500M memory, it can be 50M kernel memory tops. + + $ docker run -ti --kernel-memory 50M ubuntu:14.04 /bin/bash + +We set kernel memory without **-m**, so the processes in the container can +use as much memory as they want, but they can only use 50M kernel memory. + ### Swappiness constraint By default, a container's kernel can swap out a percentage of anonymous pages. diff --git a/man/docker-create.1.md b/man/docker-create.1.md index dd968400c8..c4243fa100 100644 --- a/man/docker-create.1.md +++ b/man/docker-create.1.md @@ -30,6 +30,7 @@ docker-create - Create a new container [**--help**] [**-i**|**--interactive**[=*false*]] [**--ipc**[=*IPC*]] +[**--kernel-memory**[=*KERNEL-MEMORY*]] [**-l**|**--label**[=*[]*]] [**--label-file**[=*[]*]] [**--link**[=*[]*]] @@ -148,6 +149,15 @@ two memory nodes. 'container:': reuses another container shared memory, semaphores and message queues 'host': use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. +**--kernel-memory**="" + Kernel memory limit (format: `[]`, where unit = b, k, m or g) + + Constrains the kernel memory available to a container. If a limit of 0 +is specified (not using `--kernel-memory`), the container's kernel memory +is not limited. If you specify a limit, it may be rounded up to a multiple +of the operating system's page size and the value can be very large, +millions of trillions. + **-l**, **--label**=[] Adds metadata to a container (e.g., --label=com.example.key=value) diff --git a/man/docker-run.1.md b/man/docker-run.1.md index d48e412573..de48ba1bf6 100644 --- a/man/docker-run.1.md +++ b/man/docker-run.1.md @@ -31,6 +31,7 @@ docker-run - Run a command in a new container [**--help**] [**-i**|**--interactive**[=*false*]] [**--ipc**[=*IPC*]] +[**--kernel-memory**[=*KERNEL-MEMORY*]] [**-l**|**--label**[=*[]*]] [**--label-file**[=*[]*]] [**--link**[=*[]*]] @@ -242,6 +243,15 @@ ENTRYPOINT. **-l**, **--label**=[] Set metadata on the container (e.g., --label com.example.key=value) +**--kernel-memory**="" + Kernel memory limit (format: `[]`, where unit = b, k, m or g) + + Constrains the kernel memory available to a container. If a limit of 0 +is specified (not using `--kernel-memory`), the container's kernel memory +is not limited. If you specify a limit, it may be rounded up to a multiple +of the operating system's page size and the value can be very large, +millions of trillions. + **--label-file**=[] Read in a line delimited file of labels