From 734205b33a4f11fa88bc6abb7b739ff9ced10664 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Mon, 16 Nov 2015 13:06:56 -0800 Subject: [PATCH] runtime-config-linux: Clarify resources vs. cgroupsPath This should help clarify the cgroupsPath setting added in #137, which was the subject of some confusion in opencontainers/runc#397. Issues I'm trying to clarify here: * If you specify a cgroupsPath, is the container added to that path or a sub-cgroup underneath it [1]? (This commit rules in favor of "added to that path") * If you specify a cgroupsPath, can the runtime modify that cgroup [2]? (This commit rules "yes, if 'resources' is specified", following [3] and the Go comment from #137 [4]). To help make the distinctions clearer, I've added a facet list to help folks think about the difference between cgroup creation, process assignment, and resource configuration. cgroupsPath is just about cgroup creation and process assignment. 'resources' is just about resource configuration. I've listed out Mrunal's first three cases [3] to be even clearer. I stayed away from the "neither are set" case, since I covered that fairly directly in #237, which that was punted back to the list [5] and has seen no further interest. So I'm not clear on what the intended semantics are there, although Mrunal's wording in [4] seems to agree with the proposal in #237. [1]: https://github.com/opencontainers/runc/pull/397#issuecomment-156527638 [2]: https://github.com/opencontainers/runc/pull/397#issuecomment-157026547 [3]: https://github.com/opencontainers/runc/pull/397#issuecomment-157146714 [4]: https://github.com/opencontainers/specs/commit/429f936ff9665fd364a402af961389dc4ece6962#diff-34c30be66233f08b447fb608ea0e66bbR30 [5]: https://groups.google.com/a/opencontainers.org/d/msg/dev/qWHoKs8Fsrk/c9mv6qXtDAAJ Message-ID: <20151029194427.GA30073@odin.tremily.us> Signed-off-by: W. Trevor King --- runtime-config-linux.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/runtime-config-linux.md b/runtime-config-linux.md index b9d633c87..b1a8a13d5 100644 --- a/runtime-config-linux.md +++ b/runtime-config-linux.md @@ -144,6 +144,12 @@ Also known as cgroups, they are used to restrict resource usage for a container cgroups provide controls to restrict cpu, memory, IO, pids and network for the container. For more information, see the [kernel cgroups documentation](https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt). +There are a few facets to this: + +* Managing the existence of cgroups within the hierarchy (`cgroupsPath`). +* Moving processes to respective cgroups. +* Configuring cgroups to apply resource limits (`resources`). + The path to the cgroups can be specified in the Spec via `cgroupsPath`. `cgroupsPath` is expected to be relative to the cgroups mount point. If `cgroupsPath` is not specified, implementations can define the default cgroup path. @@ -156,11 +162,13 @@ The cgroups will be created if they don't exist. "cgroupsPath": "/myRuntime/myContainer" ``` -`cgroupsPath` can be used to either control the cgroups hierarchy for containers or to run a new process in an existing container. +The container process will be added to the cgroups at `cgroupsPath`. You can configure a container's cgroups via the `resources` field of the Linux configuration. Do not specify `resources` unless limits have to be updated. -For example, to run a new process in an existing container without updating limits, `resources` need not be specified. +For example, to run a new process in an existing container without updating limits, specify `cgroupsPath` but not `resources`. +To run a new process in an existing container and update limits, specify both `cgroupsPath` and `resources`. +To run a new process in a new container with explicit resource limits, specify `resources` and optionally set `cgroupsPath` to a cgroup that does not yet exist. #### Disable out-of-memory killer