From de394b4b9f3e1b71bf13742e5535bf35abbd07ca Mon Sep 17 00:00:00 2001 From: Qiang Huang Date: Tue, 3 Mar 2015 11:15:34 +0800 Subject: [PATCH 1/2] docs: fix cpu.shares part in man pages The original description has some mistakes and lack of many useful information, I rewrite them to make it accurate and complete. Signed-off-by: Qiang Huang Upstream-commit: e8dc07dabc962e02876cadfe5f7b508a2453bec1 Component: engine --- components/engine/docs/man/docker-run.1.md | 43 ++++++++++++------- .../engine/docs/sources/reference/run.md | 43 ++++++++++++------- 2 files changed, 54 insertions(+), 32 deletions(-) diff --git a/components/engine/docs/man/docker-run.1.md b/components/engine/docs/man/docker-run.1.md index 7dd69841f1..b3f056effb 100644 --- a/components/engine/docs/man/docker-run.1.md +++ b/components/engine/docs/man/docker-run.1.md @@ -82,24 +82,35 @@ option can be set multiple times. **-c**, **--cpu-shares**=0 CPU shares (relative weight) - You can increase the priority of a container -with the -c option. By default, all containers run at the same priority and get -the same proportion of CPU cycles, but you can tell the kernel to give more -shares of CPU time to one or more containers when you start them via **docker -run**. + You can modify the priority of a container +with the `-c` option. By default, all containers run at the same priority +and get the same proportion of CPU cycles, the value specified must be 2 +or higher, if you are not setting `-c` or `--cpu-shares`, the default +shares of CPU time would be 1024. -The flag `-c` or `--cpu-shares` with value 0 indicates that the running -container has access to all 1024 (default) CPU shares. However, this value -can be modified to run a container with a different priority or different -proportion of CPU cycles. +CPU shares is kind of CPU bandwidth weight, the proportion will only +reflect when CPU-intensive processes are running. When tasks in one +container are idle, other containers are allowed to borrow the left-over +CPU time. -E.g., If we start three {C0, C1, C2} containers with default values -(`-c` OR `--cpu-shares` = 0) and one {C3} with (`-c` or `--cpu-shares`=512) -then C0, C1, and C2 would have access to 100% CPU shares (1024) and C3 would -only have access to 50% CPU shares (512). In the context of a time-sliced OS -with time quantum set as 100 milliseconds, containers C0, C1, and C2 will run -for full-time quantum, and container C3 will run for half-time quantum i.e 50 -milliseconds. +The actual amount of CPU time can very depending on the number of containers +running on the system. If a container have a share of 1024 and two other +containers have share of 512, when processes in all containers attempt to +use 100% of CPU, the first container would receive 50% of all CPU time, if +another container with share of 1024 is added, the first container would +only get 33% of the CPU (the rest receive 16.5%, 16.5% and 33% of CPU). + +Note that shares of CPU time are distributed per all CPU cores on multi-core +systems. Even if a container is limited to less than 100% of CPU time, it +may use 100% of each individual CPU core. E.g., if we start {C0} container +with (`-c` = 512) and {C1} with (`-c` = 1024), we start three CPU-intensive +processes (one in {C0} and two in {C1}) on a system with more than three +cores, might results in the following division of CPU shares: + +PID container CPU CPU share +100 {C0} 0 100% of CPU0 +101 {C1} 1 100% of CPU1 +102 {C1} 2 100% of CPU2 **--cap-add**=[] Add Linux capabilities diff --git a/components/engine/docs/sources/reference/run.md b/components/engine/docs/sources/reference/run.md index 8faf9ad77c..a9c2181c0f 100644 --- a/components/engine/docs/sources/reference/run.md +++ b/components/engine/docs/sources/reference/run.md @@ -329,24 +329,35 @@ We have four ways to set memory usage: It is not allowed to use more than L bytes of memory, swap *plus* memory usage is limited by S. -The operator can increase the priority of this container with -the `-c` option. By default, all containers run at the same priority and -get the same proportion of CPU cycles, but you can tell the kernel to -give more shares of CPU time to one or more containers when you start -them via Docker. +The operator can modify the priority of this container with +the `-c` option. By default, all containers run at the same priority +and get the same proportion of CPU cycles, the value specified must be 2 +or higher, if you are not setting `-c` or `--cpu-shares`, the default +shares of CPU time would be 1024. -The flag `-c` or `--cpu-shares` with value 0 indicates that the running -container has access to all 1024 (default) CPU shares. However, this value -can be modified to run a container with a different priority or different -proportion of CPU cycles. +CPU shares is kind of CPU bandwidth weight, the proportion will only +reflect when CPU-intensive processes are running. When tasks in one +container are idle, other containers are allowed to borrow the left-over +CPU time. -E.g., If we start three {C0, C1, C2} containers with default values -(`-c` OR `--cpu-shares` = 0) and one {C3} with (`-c` or `--cpu-shares`=512) -then C0, C1, and C2 would have access to 100% CPU shares (1024) and C3 would -only have access to 50% CPU shares (512). In the context of a time-sliced OS -with time quantum set as 100 milliseconds, containers C0, C1, and C2 will run -for full-time quantum, and container C3 will run for half-time quantum i.e 50 -milliseconds. +The actual amount of CPU time can very depending on the number of containers +running on the system. If a container have a share of 1024 and two other +containers have share of 512, when processes in all containers attempt to +use 100% of CPU, the first container would receive 50% of all CPU time, if +another container with share of 1024 is added, the first container would +only get 33% of the CPU (the rest receive 16.5%, 16.5% and 33% of CPU). + +Note that shares of CPU time are distributed per all CPU cores on multi-core +systems. Even if a container is limited to less than 100% of CPU time, it +may use 100% of each individual CPU core. E.g., if we start {C0} container +with (`-c` = 512) and {C1} with (`-c` = 1024), we start three CPU-intensive +processes (one in {C0} and two in {C1}) on a system with more than three +cores, might results in the following division of CPU shares: + +PID container CPU CPU share +100 {C0} 0 100% of CPU0 +101 {C1} 1 100% of CPU1 +102 {C1} 2 100% of CPU2 ## Runtime privilege, Linux capabilities, and LXC configuration From e3a22924ffc8f5f17241b6a2b7949f44e6026c21 Mon Sep 17 00:00:00 2001 From: Sven Dowideit Date: Tue, 3 Mar 2015 18:17:46 -0800 Subject: [PATCH 2/2] fix to cpu.shares documentation by @hqhq Signed-off-by: Sven Dowideit Upstream-commit: 26e5a9d76a802662bf287ce9de1f98988749636a Component: engine --- components/engine/docs/man/docker-run.1.md | 53 +++++++++-------- .../docs/sources/reference/commandline/cli.md | 3 +- .../engine/docs/sources/reference/run.md | 59 +++++++++++-------- 3 files changed, 63 insertions(+), 52 deletions(-) diff --git a/components/engine/docs/man/docker-run.1.md b/components/engine/docs/man/docker-run.1.md index b3f056effb..9262b91e39 100644 --- a/components/engine/docs/man/docker-run.1.md +++ b/components/engine/docs/man/docker-run.1.md @@ -82,35 +82,38 @@ option can be set multiple times. **-c**, **--cpu-shares**=0 CPU shares (relative weight) - You can modify the priority of a container -with the `-c` option. By default, all containers run at the same priority -and get the same proportion of CPU cycles, the value specified must be 2 -or higher, if you are not setting `-c` or `--cpu-shares`, the default -shares of CPU time would be 1024. + By default, all containers get the same proportion of CPU cycles. This proportion +can be modified by changing the container's CPU share weighting relative +to the weighting of all other running containers. -CPU shares is kind of CPU bandwidth weight, the proportion will only -reflect when CPU-intensive processes are running. When tasks in one -container are idle, other containers are allowed to borrow the left-over -CPU time. +To modify the proportion from the default of 1024, use the **-c** or **--cpu-shares** +flag to set the weighting to 2 or higher. -The actual amount of CPU time can very depending on the number of containers -running on the system. If a container have a share of 1024 and two other -containers have share of 512, when processes in all containers attempt to -use 100% of CPU, the first container would receive 50% of all CPU time, if -another container with share of 1024 is added, the first container would -only get 33% of the CPU (the rest receive 16.5%, 16.5% and 33% of CPU). +The proportion will only apply when CPU-intensive processes are running. +When tasks in one container are idle, other containers can use the +left-over CPU time. The actual amount of CPU time will vary depending on +the number of containers running on the system. -Note that shares of CPU time are distributed per all CPU cores on multi-core -systems. Even if a container is limited to less than 100% of CPU time, it -may use 100% of each individual CPU core. E.g., if we start {C0} container -with (`-c` = 512) and {C1} with (`-c` = 1024), we start three CPU-intensive -processes (one in {C0} and two in {C1}) on a system with more than three -cores, might results in the following division of CPU shares: +For example, consider three containers, one has a cpu-share of 1024 and +two others have a cpu-share setting of 512. When processes in all three +containers attempt to use 100% of CPU, the first container would receive +50% of the total CPU time. If you add a fouth container with a cpu-share +of 1024, the first container only gets 33% of the CPU. The remaining containers +receive 16.5%, 16.5% and 33% of the CPU. -PID container CPU CPU share -100 {C0} 0 100% of CPU0 -101 {C1} 1 100% of CPU1 -102 {C1} 2 100% of CPU2 +On a multi-core system, the shares of CPU time are distributed over all CPU +cores. Even if a container is limited to less than 100% of CPU time, it can +use 100% of each individual CPU core. + +For example, consider a system with more than three cores. If you start one +container **{C0}** with **-c=512** running one process, and another container +**{C1}** with **-c=1024** running two processes, this can result in the following +division of CPU shares: + + PID container CPU CPU share + 100 {C0} 0 100% of CPU0 + 101 {C1} 1 100% of CPU1 + 102 {C1} 2 100% of CPU2 **--cap-add**=[] Add Linux capabilities diff --git a/components/engine/docs/sources/reference/commandline/cli.md b/components/engine/docs/sources/reference/commandline/cli.md index eb61872dae..9e026d086c 100644 --- a/components/engine/docs/sources/reference/commandline/cli.md +++ b/components/engine/docs/sources/reference/commandline/cli.md @@ -817,7 +817,8 @@ container at any point. This is useful when you want to set up a container configuration ahead of time so that it is ready to start when you need it. -Please see the [run command](#run) section for more details. +Please see the [run command](#run) section and the [Docker run reference]( +/reference/run/) for more details. #### Examples diff --git a/components/engine/docs/sources/reference/run.md b/components/engine/docs/sources/reference/run.md index a9c2181c0f..9108a86ad1 100644 --- a/components/engine/docs/sources/reference/run.md +++ b/components/engine/docs/sources/reference/run.md @@ -311,7 +311,9 @@ container: -m="": 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) - -c=0 : CPU shares (relative weight) + -c, --cpu-shares=0 CPU shares (relative weight) + +### Memory constraints We have four ways to set memory usage: - memory=inf, memory-swap=inf (not specify any of them) @@ -329,35 +331,40 @@ We have four ways to set memory usage: It is not allowed to use more than L bytes of memory, swap *plus* memory usage is limited by S. -The operator can modify the priority of this container with -the `-c` option. By default, all containers run at the same priority -and get the same proportion of CPU cycles, the value specified must be 2 -or higher, if you are not setting `-c` or `--cpu-shares`, the default -shares of CPU time would be 1024. +### CPU share constraint -CPU shares is kind of CPU bandwidth weight, the proportion will only -reflect when CPU-intensive processes are running. When tasks in one -container are idle, other containers are allowed to borrow the left-over -CPU time. +By default, all containers get the same proportion of CPU cycles. This proportion +can be modified by changing the container's CPU share weighting relative +to the weighting of all other running containers. -The actual amount of CPU time can very depending on the number of containers -running on the system. If a container have a share of 1024 and two other -containers have share of 512, when processes in all containers attempt to -use 100% of CPU, the first container would receive 50% of all CPU time, if -another container with share of 1024 is added, the first container would -only get 33% of the CPU (the rest receive 16.5%, 16.5% and 33% of CPU). +To modify the proportion from the default of 1024, use the `-c` or `--cpu-shares` +flag to set the weighting to 2 or higher. -Note that shares of CPU time are distributed per all CPU cores on multi-core -systems. Even if a container is limited to less than 100% of CPU time, it -may use 100% of each individual CPU core. E.g., if we start {C0} container -with (`-c` = 512) and {C1} with (`-c` = 1024), we start three CPU-intensive -processes (one in {C0} and two in {C1}) on a system with more than three -cores, might results in the following division of CPU shares: +The proportion will only apply when CPU-intensive processes are running. +When tasks in one container are idle, other containers can use the +left-over CPU time. The actual amount of CPU time will vary depending on +the number of containers running on the system. -PID container CPU CPU share -100 {C0} 0 100% of CPU0 -101 {C1} 1 100% of CPU1 -102 {C1} 2 100% of CPU2 +For example, consider three containers, one has a cpu-share of 1024 and +two others have a cpu-share setting of 512. When processes in all three +containers attempt to use 100% of CPU, the first container would receive +50% of the total CPU time. If you add a fouth container with a cpu-share +of 1024, the first container only gets 33% of the CPU. The remaining containers +receive 16.5%, 16.5% and 33% of the CPU. + +On a multi-core system, the shares of CPU time are distributed over all CPU +cores. Even if a container is limited to less than 100% of CPU time, it can +use 100% of each individual CPU core. + +For example, consider a system with more than three cores. If you start one +container `{C0}` with `-c=512` running one process, and another container +`{C1}` with `-c=1024` running two processes, this can result in the following +division of CPU shares: + + PID container CPU CPU share + 100 {C0} 0 100% of CPU0 + 101 {C1} 1 100% of CPU1 + 102 {C1} 2 100% of CPU2 ## Runtime privilege, Linux capabilities, and LXC configuration