About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / cgroups / unified-hierarchy.txt

Custom Search

Based on kernel version 3.19. Page generated on 2015-02-13 21:16 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 support the unified hierarchy and are not bound
98	to other hierarchies are automatically bound to unified hierarchy and
99	show up at the root of it.  Controllers which are enabled only in the
100	root of unified hierarchy can be bound to other hierarchies.  This
101	allows mixing unified hierarchy with the traditional multiple
102	hierarchies in a fully backward compatible way.
104	For development purposes, the following boot parameter makes all
105	controllers to appear on the unified hierarchy whether supported or
106	not.
108	 cgroup__DEVEL__legacy_files_on_dfl
110	A controller can be moved across hierarchies only after the controller
111	is no longer referenced in its current hierarchy.  Because per-cgroup
112	controller states are destroyed asynchronously and controllers may
113	have lingering references, a controller may not show up immediately on
114	the unified hierarchy after the final umount of the previous
115	hierarchy.  Similarly, a controller should be fully disabled to be
116	moved out of the unified hierarchy and it may take some time for the
117	disabled controller to become available for other hierarchies;
118	furthermore, due to dependencies among controllers, other controllers
119	may need to be disabled too.
121	While useful for development and manual configurations, dynamically
122	moving controllers between the unified and other hierarchies is
123	strongly discouraged for production use.  It is recommended to decide
124	the hierarchies and controller associations before starting using the
125	controllers.
128	2-2. cgroup.subtree_control
130	All cgroups on unified hierarchy have a "cgroup.subtree_control" file
131	which governs which controllers are enabled on the children of the
132	cgroup.  Let's assume a hierarchy like the following.
134	  root - A - B - C
135	               \ D
137	root's "cgroup.subtree_control" file determines which controllers are
138	enabled on A.  A's on B.  B's on C and D.  This coincides with the
139	fact that controllers on the immediate sub-level are used to
140	distribute the resources of the parent.  In fact, it's natural to
141	assume that resource control knobs of a child belong to its parent.
142	Enabling a controller in a "cgroup.subtree_control" file declares that
143	distribution of the respective resources of the cgroup will be
144	controlled.  Note that this means that controller enable states are
145	shared among siblings.
147	When read, the file contains a space-separated list of currently
148	enabled controllers.  A write to the file should contain a
149	space-separated list of controllers with '+' or '-' prefixed (without
150	the quotes).  Controllers prefixed with '+' are enabled and '-'
151	disabled.  If a controller is listed multiple times, the last entry
152	wins.  The specific operations are executed atomically - either all
153	succeed or fail.
156	2-3. cgroup.controllers
158	Read-only "cgroup.controllers" file contains a space-separated list of
159	controllers which can be enabled in the cgroup's
160	"cgroup.subtree_control" file.
162	In the root cgroup, this lists controllers which are not bound to
163	other hierarchies and the content changes as controllers are bound to
164	and unbound from other hierarchies.
166	In non-root cgroups, the content of this file equals that of the
167	parent's "cgroup.subtree_control" file as only controllers enabled
168	from the parent can be used in its children.
171	3. Structural Constraints
173	3-1. Top-down
175	As it doesn't make sense to nest control of an uncontrolled resource,
176	all non-root "cgroup.subtree_control" files can only contain
177	controllers which are enabled in the parent's "cgroup.subtree_control"
178	file.  A controller can be enabled only if the parent has the
179	controller enabled and a controller can't be disabled if one or more
180	children have it enabled.
183	3-2. No internal tasks
185	One long-standing issue that cgroup faces is the competition between
186	tasks belonging to the parent cgroup and its children cgroups.  This
187	is inherently nasty as two different types of entities compete and
188	there is no agreed-upon obvious way to handle it.  Different
189	controllers are doing different things.
191	The cpu controller considers tasks and cgroups as equivalents and maps
192	nice levels to cgroup weights.  This works for some cases but falls
193	flat when children should be allocated specific ratios of CPU cycles
194	and the number of internal tasks fluctuates - the ratios constantly
195	change as the number of competing entities fluctuates.  There also are
196	other issues.  The mapping from nice level to weight isn't obvious or
197	universal, and there are various other knobs which simply aren't
198	available for tasks.
200	The blkio controller implicitly creates a hidden leaf node for each
201	cgroup to host the tasks.  The hidden leaf has its own copies of all
202	the knobs with "leaf_" prefixed.  While this allows equivalent control
203	over internal tasks, it's with serious drawbacks.  It always adds an
204	extra layer of nesting which may not be necessary, makes the interface
205	messy and significantly complicates the implementation.
207	The memory controller currently doesn't have a way to control what
208	happens between internal tasks and child cgroups and the behavior is
209	not clearly defined.  There have been attempts to add ad-hoc behaviors
210	and knobs to tailor the behavior to specific workloads.  Continuing
211	this direction will lead to problems which will be extremely difficult
212	to resolve in the long term.
214	Multiple controllers struggle with internal tasks and came up with
215	different ways to deal with it; unfortunately, all the approaches in
216	use now are severely flawed and, furthermore, the widely different
217	behaviors make cgroup as whole highly inconsistent.
219	It is clear that this is something which needs to be addressed from
220	cgroup core proper in a uniform way so that controllers don't need to
221	worry about it and cgroup as a whole shows a consistent and logical
222	behavior.  To achieve that, unified hierarchy enforces the following
223	structural constraint:
225	 Except for the root, only cgroups which don't contain any task may
226	 have controllers enabled in their "cgroup.subtree_control" files.
228	Combined with other properties, this guarantees that, when a
229	controller is looking at the part of the hierarchy which has it
230	enabled, tasks are always only on the leaves.  This rules out
231	situations where child cgroups compete against internal tasks of the
232	parent.
234	There are two things to note.  Firstly, the root cgroup is exempt from
235	the restriction.  Root contains tasks and anonymous resource
236	consumption which can't be associated with any other cgroup and
237	requires special treatment from most controllers.  How resource
238	consumption in the root cgroup is governed is up to each controller.
240	Secondly, the restriction doesn't take effect if there is no enabled
241	controller in the cgroup's "cgroup.subtree_control" file.  This is
242	important as otherwise it wouldn't be possible to create children of a
243	populated cgroup.  To control resource distribution of a cgroup, the
244	cgroup must create children and transfer all its tasks to the children
245	before enabling controllers in its "cgroup.subtree_control" file.
248	4. Other Changes
250	4-1. [Un]populated Notification
252	cgroup users often need a way to determine when a cgroup's
253	subhierarchy becomes empty so that it can be cleaned up.  cgroup
254	currently provides release_agent for it; unfortunately, this mechanism
255	is riddled with issues.
257	- It delivers events by forking and execing a userland binary
258	  specified as the release_agent.  This is a long deprecated method of
259	  notification delivery.  It's extremely heavy, slow and cumbersome to
260	  integrate with larger infrastructure.
262	- There is single monitoring point at the root.  There's no way to
263	  delegate management of a subtree.
265	- The event isn't recursive.  It triggers when a cgroup doesn't have
266	  any tasks or child cgroups.  Events for internal nodes trigger only
267	  after all children are removed.  This again makes it impossible to
268	  delegate management of a subtree.
270	- Events are filtered from the kernel side.  A "notify_on_release"
271	  file is used to subscribe to or suppress release events.  This is
272	  unnecessarily complicated and probably done this way because event
273	  delivery itself was expensive.
275	Unified hierarchy implements an interface file "cgroup.populated"
276	which can be used to monitor whether the cgroup's subhierarchy has
277	tasks in it or not.  Its value is 0 if there is no task in the cgroup
278	and its descendants; otherwise, 1.  poll and [id]notify events are
279	triggered when the value changes.
281	This is significantly lighter and simpler and trivially allows
282	delegating management of subhierarchy - subhierarchy monitoring can
283	block further propagation simply by putting itself or another process
284	in the subhierarchy and monitor events that it's interested in from
285	there without interfering with monitoring higher in the tree.
287	In unified hierarchy, the release_agent mechanism is no longer
288	supported and the interface files "release_agent" and
289	"notify_on_release" do not exist.
292	4-2. Other Core Changes
294	- None of the mount options is allowed.
296	- remount is disallowed.
298	- rename(2) is disallowed.
300	- The "tasks" file is removed.  Everything should at process
301	  granularity.  Use the "cgroup.procs" file instead.
303	- The "cgroup.procs" file is not sorted.  pids will be unique unless
304	  they got recycled in-between reads.
306	- The "cgroup.clone_children" file is removed.
309	4-3. Per-Controller Changes
311	4-3-1. blkio
313	- blk-throttle becomes properly hierarchical.
316	4-3-2. cpuset
318	- Tasks are kept in empty cpusets after hotplug and take on the masks
319	  of the nearest non-empty ancestor, instead of being moved to it.
321	- A task can be moved into an empty cpuset, and again it takes on the
322	  masks of the nearest non-empty ancestor.
325	4-3-3. memory
327	- use_hierarchy is on by default and the cgroup file for the flag is
328	  not created.
331	5. Planned Changes
333	5-1. CAP for resource control
335	Unified hierarchy will require one of the capabilities(7), which is
336	yet to be decided, for all resource control related knobs.  Process
337	organization operations - creation of sub-cgroups and migration of
338	processes in sub-hierarchies may be delegated by changing the
339	ownership and/or permissions on the cgroup directory and
340	"cgroup.procs" interface file; however, all operations which affect
341	resource control - writes to a "cgroup.subtree_control" file or any
342	controller-specific knobs - will require an explicit CAP privilege.
344	This, in part, is to prevent the cgroup interface from being
345	inadvertently promoted to programmable API used by non-privileged
346	binaries.  cgroup exposes various aspects of the system in ways which
347	aren't properly abstracted for direct consumption by regular programs.
348	This is an administration interface much closer to sysctl knobs than
349	system calls.  Even the basic access model, being filesystem path
350	based, isn't suitable for direct consumption.  There's no way to
351	access "my cgroup" in a race-free way or make multiple operations
352	atomic against migration to another cgroup.
354	Another aspect is that, for better or for worse, the cgroup interface
355	goes through far less scrutiny than regular interfaces for
356	unprivileged userland.  The upside is that cgroup is able to expose
357	useful features which may not be suitable for general consumption in a
358	reasonable time frame.  It provides a relatively short path between
359	internal details and userland-visible interface.  Of course, this
360	shortcut comes with high risk.  We go through what we go through for
361	general kernel APIs for good reasons.  It may end up leaking internal
362	details in a way which can exert significant pain by locking the
363	kernel into a contract that can't be maintained in a reasonable
364	manner.
366	Also, due to the specific nature, cgroup and its controllers don't
367	tend to attract attention from a wide scope of developers.  cgroup's
368	short history is already fraught with severely mis-designed
369	interfaces, unnecessary commitments to and exposing of internal
370	details, broken and dangerous implementations of various features.
372	Keeping cgroup as an administration interface is both advantageous for
373	its role and imperative given its nature.  Some of the cgroup features
374	may make sense for unprivileged access.  If deemed justified, those
375	must be further abstracted and implemented as a different interface,
376	be it a system call or process-private filesystem, and survive through
377	the scrutiny that any interface for general consumption is required to
378	go through.
380	Requiring CAP is not a complete solution but should serve as a
381	significant deterrent against spraying cgroup usages in non-privileged
382	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.