About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / cgroups / unified-hierarchy.txt

Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:36 EST.

2	Cgroup unified hierarchy
4	April, 2014		Tejun Heo <tj@kernel.org>
6	This document describes the changes made by unified hierarchy and
7	their rationales.  It will eventually be merged into the main cgroup
8	documentation.
12	1. Background
13	2. Basic Operation
14	  2-1. Mounting
15	  2-2. cgroup.subtree_control
16	  2-3. cgroup.controllers
17	3. Structural Constraints
18	  3-1. Top-down
19	  3-2. No internal tasks
20	4. Other Changes
21	  4-1. [Un]populated Notification
22	  4-2. Other Core Changes
23	  4-3. Per-Controller Changes
24	    4-3-1. blkio
25	    4-3-2. cpuset
26	    4-3-3. memory
27	5. Planned Changes
28	  5-1. CAP for resource control
31	1. Background
33	cgroup allows an arbitrary number of hierarchies and each hierarchy
34	can host any number of controllers.  While this seems to provide a
35	high level of flexibility, it isn't quite useful in practice.
37	For example, as there is only one instance of each controller, utility
38	type controllers such as freezer which can be useful in all
39	hierarchies can only be used in one.  The issue is exacerbated by the
40	fact that controllers can't be moved around once hierarchies are
41	populated.  Another issue is that all controllers bound to a hierarchy
42	are forced to have exactly the same view of the hierarchy.  It isn't
43	possible to vary the granularity depending on the specific controller.
45	In practice, these issues heavily limit which controllers can be put
46	on the same hierarchy and most configurations resort to putting each
47	controller on its own hierarchy.  Only closely related ones, such as
48	the cpu and cpuacct controllers, make sense to put on the same
49	hierarchy.  This often means that userland ends up managing multiple
50	similar hierarchies repeating the same steps on each hierarchy
51	whenever a hierarchy management operation is necessary.
53	Unfortunately, support for multiple hierarchies comes at a steep cost.
54	Internal implementation in cgroup core proper is dazzlingly
55	complicated but more importantly the support for multiple hierarchies
56	restricts how cgroup is used in general and what controllers can do.
58	There's no limit on how many hierarchies there may be, which means
59	that a task's cgroup membership can't be described in finite length.
60	The key may contain any varying number of entries and is unlimited in
61	length, which makes it highly awkward to handle and leads to addition
62	of controllers which exist only to identify membership, which in turn
63	exacerbates the original problem.
65	Also, as a controller can't have any expectation regarding what shape
66	of hierarchies other controllers would be on, each controller has to
67	assume that all other controllers are operating on completely
68	orthogonal hierarchies.  This makes it impossible, or at least very
69	cumbersome, for controllers to cooperate with each other.
71	In most use cases, putting controllers on hierarchies which are
72	completely orthogonal to each other isn't necessary.  What usually is
73	called for is the ability to have differing levels of granularity
74	depending on the specific controller.  In other words, hierarchy may
75	be collapsed from leaf towards root when viewed from specific
76	controllers.  For example, a given configuration might not care about
77	how memory is distributed beyond a certain level while still wanting
78	to control how CPU cycles are distributed.
80	Unified hierarchy is the next version of cgroup interface.  It aims to
81	address the aforementioned issues by having more structure while
82	retaining enough flexibility for most use cases.  Various other
83	general and controller-specific interface issues are also addressed in
84	the process.
87	2. Basic Operation
89	2-1. Mounting
91	Currently, unified hierarchy can be mounted with the following mount
92	command.  Note that this is still under development and scheduled to
93	change soon.
95	 mount -t cgroup -o __DEVEL__sane_behavior cgroup $MOUNT_POINT
97	All controllers which are not bound to other hierarchies are
98	automatically bound to unified hierarchy and show up at the root of
99	it.  Controllers which are enabled only in the root of unified
100	hierarchy can be bound to other hierarchies at any time.  This allows
101	mixing unified hierarchy with the traditional multiple hierarchies in
102	a fully backward compatible way.
105	2-2. cgroup.subtree_control
107	All cgroups on unified hierarchy have a "cgroup.subtree_control" file
108	which governs which controllers are enabled on the children of the
109	cgroup.  Let's assume a hierarchy like the following.
111	  root - A - B - C
112	               \ D
114	root's "cgroup.subtree_control" file determines which controllers are
115	enabled on A.  A's on B.  B's on C and D.  This coincides with the
116	fact that controllers on the immediate sub-level are used to
117	distribute the resources of the parent.  In fact, it's natural to
118	assume that resource control knobs of a child belong to its parent.
119	Enabling a controller in a "cgroup.subtree_control" file declares that
120	distribution of the respective resources of the cgroup will be
121	controlled.  Note that this means that controller enable states are
122	shared among siblings.
124	When read, the file contains a space-separated list of currently
125	enabled controllers.  A write to the file should contain a
126	space-separated list of controllers with '+' or '-' prefixed (without
127	the quotes).  Controllers prefixed with '+' are enabled and '-'
128	disabled.  If a controller is listed multiple times, the last entry
129	wins.  The specific operations are executed atomically - either all
130	succeed or fail.
133	2-3. cgroup.controllers
135	Read-only "cgroup.controllers" file contains a space-separated list of
136	controllers which can be enabled in the cgroup's
137	"cgroup.subtree_control" file.
139	In the root cgroup, this lists controllers which are not bound to
140	other hierarchies and the content changes as controllers are bound to
141	and unbound from other hierarchies.
143	In non-root cgroups, the content of this file equals that of the
144	parent's "cgroup.subtree_control" file as only controllers enabled
145	from the parent can be used in its children.
148	3. Structural Constraints
150	3-1. Top-down
152	As it doesn't make sense to nest control of an uncontrolled resource,
153	all non-root "cgroup.subtree_control" files can only contain
154	controllers which are enabled in the parent's "cgroup.subtree_control"
155	file.  A controller can be enabled only if the parent has the
156	controller enabled and a controller can't be disabled if one or more
157	children have it enabled.
160	3-2. No internal tasks
162	One long-standing issue that cgroup faces is the competition between
163	tasks belonging to the parent cgroup and its children cgroups.  This
164	is inherently nasty as two different types of entities compete and
165	there is no agreed-upon obvious way to handle it.  Different
166	controllers are doing different things.
168	The cpu controller considers tasks and cgroups as equivalents and maps
169	nice levels to cgroup weights.  This works for some cases but falls
170	flat when children should be allocated specific ratios of CPU cycles
171	and the number of internal tasks fluctuates - the ratios constantly
172	change as the number of competing entities fluctuates.  There also are
173	other issues.  The mapping from nice level to weight isn't obvious or
174	universal, and there are various other knobs which simply aren't
175	available for tasks.
177	The blkio controller implicitly creates a hidden leaf node for each
178	cgroup to host the tasks.  The hidden leaf has its own copies of all
179	the knobs with "leaf_" prefixed.  While this allows equivalent control
180	over internal tasks, it's with serious drawbacks.  It always adds an
181	extra layer of nesting which may not be necessary, makes the interface
182	messy and significantly complicates the implementation.
184	The memory controller currently doesn't have a way to control what
185	happens between internal tasks and child cgroups and the behavior is
186	not clearly defined.  There have been attempts to add ad-hoc behaviors
187	and knobs to tailor the behavior to specific workloads.  Continuing
188	this direction will lead to problems which will be extremely difficult
189	to resolve in the long term.
191	Multiple controllers struggle with internal tasks and came up with
192	different ways to deal with it; unfortunately, all the approaches in
193	use now are severely flawed and, furthermore, the widely different
194	behaviors make cgroup as whole highly inconsistent.
196	It is clear that this is something which needs to be addressed from
197	cgroup core proper in a uniform way so that controllers don't need to
198	worry about it and cgroup as a whole shows a consistent and logical
199	behavior.  To achieve that, unified hierarchy enforces the following
200	structural constraint:
202	 Except for the root, only cgroups which don't contain any task may
203	 have controllers enabled in their "cgroup.subtree_control" files.
205	Combined with other properties, this guarantees that, when a
206	controller is looking at the part of the hierarchy which has it
207	enabled, tasks are always only on the leaves.  This rules out
208	situations where child cgroups compete against internal tasks of the
209	parent.
211	There are two things to note.  Firstly, the root cgroup is exempt from
212	the restriction.  Root contains tasks and anonymous resource
213	consumption which can't be associated with any other cgroup and
214	requires special treatment from most controllers.  How resource
215	consumption in the root cgroup is governed is up to each controller.
217	Secondly, the restriction doesn't take effect if there is no enabled
218	controller in the cgroup's "cgroup.subtree_control" file.  This is
219	important as otherwise it wouldn't be possible to create children of a
220	populated cgroup.  To control resource distribution of a cgroup, the
221	cgroup must create children and transfer all its tasks to the children
222	before enabling controllers in its "cgroup.subtree_control" file.
225	4. Other Changes
227	4-1. [Un]populated Notification
229	cgroup users often need a way to determine when a cgroup's
230	subhierarchy becomes empty so that it can be cleaned up.  cgroup
231	currently provides release_agent for it; unfortunately, this mechanism
232	is riddled with issues.
234	- It delivers events by forking and execing a userland binary
235	  specified as the release_agent.  This is a long deprecated method of
236	  notification delivery.  It's extremely heavy, slow and cumbersome to
237	  integrate with larger infrastructure.
239	- There is single monitoring point at the root.  There's no way to
240	  delegate management of a subtree.
242	- The event isn't recursive.  It triggers when a cgroup doesn't have
243	  any tasks or child cgroups.  Events for internal nodes trigger only
244	  after all children are removed.  This again makes it impossible to
245	  delegate management of a subtree.
247	- Events are filtered from the kernel side.  A "notify_on_release"
248	  file is used to subscribe to or suppress release events.  This is
249	  unnecessarily complicated and probably done this way because event
250	  delivery itself was expensive.
252	Unified hierarchy implements an interface file "cgroup.populated"
253	which can be used to monitor whether the cgroup's subhierarchy has
254	tasks in it or not.  Its value is 0 if there is no task in the cgroup
255	and its descendants; otherwise, 1.  poll and [id]notify events are
256	triggered when the value changes.
258	This is significantly lighter and simpler and trivially allows
259	delegating management of subhierarchy - subhierarchy monitoring can
260	block further propagation simply by putting itself or another process
261	in the subhierarchy and monitor events that it's interested in from
262	there without interfering with monitoring higher in the tree.
264	In unified hierarchy, the release_agent mechanism is no longer
265	supported and the interface files "release_agent" and
266	"notify_on_release" do not exist.
269	4-2. Other Core Changes
271	- None of the mount options is allowed.
273	- remount is disallowed.
275	- rename(2) is disallowed.
277	- The "tasks" file is removed.  Everything should at process
278	  granularity.  Use the "cgroup.procs" file instead.
280	- The "cgroup.procs" file is not sorted.  pids will be unique unless
281	  they got recycled in-between reads.
283	- The "cgroup.clone_children" file is removed.
286	4-3. Per-Controller Changes
288	4-3-1. blkio
290	- blk-throttle becomes properly hierarchical.
293	4-3-2. cpuset
295	- Tasks are kept in empty cpusets after hotplug and take on the masks
296	  of the nearest non-empty ancestor, instead of being moved to it.
298	- A task can be moved into an empty cpuset, and again it takes on the
299	  masks of the nearest non-empty ancestor.
302	4-3-3. memory
304	- use_hierarchy is on by default and the cgroup file for the flag is
305	  not created.
308	5. Planned Changes
310	5-1. CAP for resource control
312	Unified hierarchy will require one of the capabilities(7), which is
313	yet to be decided, for all resource control related knobs.  Process
314	organization operations - creation of sub-cgroups and migration of
315	processes in sub-hierarchies may be delegated by changing the
316	ownership and/or permissions on the cgroup directory and
317	"cgroup.procs" interface file; however, all operations which affect
318	resource control - writes to a "cgroup.subtree_control" file or any
319	controller-specific knobs - will require an explicit CAP privilege.
321	This, in part, is to prevent the cgroup interface from being
322	inadvertently promoted to programmable API used by non-privileged
323	binaries.  cgroup exposes various aspects of the system in ways which
324	aren't properly abstracted for direct consumption by regular programs.
325	This is an administration interface much closer to sysctl knobs than
326	system calls.  Even the basic access model, being filesystem path
327	based, isn't suitable for direct consumption.  There's no way to
328	access "my cgroup" in a race-free way or make multiple operations
329	atomic against migration to another cgroup.
331	Another aspect is that, for better or for worse, the cgroup interface
332	goes through far less scrutiny than regular interfaces for
333	unprivileged userland.  The upside is that cgroup is able to expose
334	useful features which may not be suitable for general consumption in a
335	reasonable time frame.  It provides a relatively short path between
336	internal details and userland-visible interface.  Of course, this
337	shortcut comes with high risk.  We go through what we go through for
338	general kernel APIs for good reasons.  It may end up leaking internal
339	details in a way which can exert significant pain by locking the
340	kernel into a contract that can't be maintained in a reasonable
341	manner.
343	Also, due to the specific nature, cgroup and its controllers don't
344	tend to attract attention from a wide scope of developers.  cgroup's
345	short history is already fraught with severely mis-designed
346	interfaces, unnecessary commitments to and exposing of internal
347	details, broken and dangerous implementations of various features.
349	Keeping cgroup as an administration interface is both advantageous for
350	its role and imperative given its nature.  Some of the cgroup features
351	may make sense for unprivileged access.  If deemed justified, those
352	must be further abstracted and implemented as a different interface,
353	be it a system call or process-private filesystem, and survive through
354	the scrutiny that any interface for general consumption is required to
355	go through.
357	Requiring CAP is not a complete solution but should serve as a
358	significant deterrent against spraying cgroup usages in non-privileged
359	programs.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.