From 9ffd72407bb67fcf24708f6d8df160aa0334a483 Mon Sep 17 00:00:00 2001 From: Aleksa Sarai Date: Sat, 11 Jun 2016 00:42:53 +1000 Subject: [PATCH 1/4] config-linux: cleanup cgroup wording Some of the wording was a bit clumsy (and incorrect, by conflating different concepts in control groups as "cgroups"). Signed-off-by: Aleksa Sarai --- config-linux.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/config-linux.md b/config-linux.md index b206fa04c..0e734cbc1 100644 --- a/config-linux.md +++ b/config-linux.md @@ -154,29 +154,28 @@ In addition to any devices configured with this setting, the runtime MUST also s ## Control groups Also known as cgroups, they are used to restrict resource usage for a container and handle device access. -cgroups provide controls to restrict cpu, memory, IO, pids and network for the container. +cgroups provide controls (through controllers) to restrict cpu, memory, IO, pids and network for the container. For more information, see the [kernel cgroups documentation][cgroup-v1]. The path to the cgroups can be specified in the Spec via `cgroupsPath`. +`cgroupsPath` can be used to either control the cgroup hierarchy for containers or to run a new process in an existing container. `cgroupsPath` is expected to be relative to the cgroups mount point. If `cgroupsPath` is not specified, implementations can define the default cgroup path. Implementations of the Spec can choose to name cgroups in any manner. The Spec does not include naming schema for cgroups. -The Spec does not support [split hierarchy][cgroup-v2]. +The Spec does not support per-controller paths for the reasons discussed in the [cgroupv2 documentation][cgroup-v2]. The cgroups will be created if they don't exist. +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. + ###### Example ```json "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. - -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. - #### Device whitelist `devices` is an array of entries to control the [device whitelist][cgroup-v1-devices]. From 0c440a216c86fdeef79af61a681d3bb82f34b162 Mon Sep 17 00:00:00 2001 From: Aleksa Sarai Date: Wed, 8 Jun 2016 22:54:18 +1000 Subject: [PATCH 2/4] config-linux: clarify cgroupsPath Clarify some of the confusion with cgroupsPath. Due to systemd, we cannot require that relative paths be treated in any specific way. In addition, add a line stating that not all values of cgroupsPath are required to be valid (and that runtimes must error out if they have an invalid cgroup path). However, any given value of cgroupsPath should provide consistent results. Signed-off-by: Aleksa Sarai --- config-linux.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/config-linux.md b/config-linux.md index 0e734cbc1..099d468b3 100644 --- a/config-linux.md +++ b/config-linux.md @@ -159,8 +159,13 @@ For more information, see the [kernel cgroups documentation][cgroup-v1]. The path to the cgroups can be specified in the Spec via `cgroupsPath`. `cgroupsPath` can be used to either control the cgroup hierarchy for containers or to run a new process in an existing container. -`cgroupsPath` is expected to be relative to the cgroups mount point. -If `cgroupsPath` is not specified, implementations can define the default cgroup path. +If `cgroupsPath` is: +* ... an absolute path (starting with `/`), the runtime MUST take the path to be relative to the cgroup mount point. +* ... a relative path (not starting with `/`), the runtime MAY interpret the path relative to a runtime-determined location in the cgroup hierarchy. +* ... not specified, the runtime MAY define the default cgroup path. +Runtimes MAY consider certain `cgroupsPath` values to be invalid, and MUST generate an error if this is the case. +If a `cgroupsPath` value is specified, the runtime MUST consistently attach to the same place in the cgroup hierarchy given the same value of `cgroupsPath`. + Implementations of the Spec can choose to name cgroups in any manner. The Spec does not include naming schema for cgroups. The Spec does not support per-controller paths for the reasons discussed in the [cgroupv2 documentation][cgroup-v2]. From 4291fd1d5a64cb1d3e00dd50fe53cb5fc282f882 Mon Sep 17 00:00:00 2001 From: Aleksa Sarai Date: Wed, 8 Jun 2016 22:56:17 +1000 Subject: [PATCH 3/4] config-linux: allow lazy cgroup handling Make explicit that runtimes only have to attach to the bare minimum number of cgroups in order to fulfil the users' requirements. However, runtimes are of course allowed to attach to more than the bare minimum. Signed-off-by: Aleksa Sarai --- config-linux.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/config-linux.md b/config-linux.md index 099d468b3..43db55c64 100644 --- a/config-linux.md +++ b/config-linux.md @@ -175,6 +175,9 @@ You can configure a container's cgroups via the `resources` field of the Linux c 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. +A runtime MUST at least use the minimum set of cgroup controllers required to fulfill the `resources` settings. +However, a runtime MAY attach the container process to additional cgroup controllers supported by the system. + ###### Example ```json From 4ed839e7479fd447e2e348fca84c615ae3c786f8 Mon Sep 17 00:00:00 2001 From: Aleksa Sarai Date: Thu, 7 Jul 2016 17:46:35 +1000 Subject: [PATCH 4/4] config-linux: add example of cgroup resource limits The example section looks very sparse otherwise. Signed-off-by: Aleksa Sarai --- config-linux.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/config-linux.md b/config-linux.md index 43db55c64..6555f526e 100644 --- a/config-linux.md +++ b/config-linux.md @@ -181,7 +181,19 @@ However, a runtime MAY attach the container process to additional cgroup control ###### Example ```json - "cgroupsPath": "/myRuntime/myContainer" + "cgroupsPath": "/myRuntime/myContainer", + "resources": { + "memory": { + "limit": 100000, + "reservation": 200000 + }, + "devices": [ + { + "allow": false, + "access": "rwm" + } + ] + } ``` #### Device whitelist