blob: 71daa35ec2d9201d2a4647e0a088af3ab36bbae3 [file] [log] [blame]
Tejun Heo65731572014-04-25 18:28:02 -04001
2Cgroup unified hierarchy
3
4April, 2014 Tejun Heo <tj@kernel.org>
5
6This document describes the changes made by unified hierarchy and
7their rationales. It will eventually be merged into the main cgroup
8documentation.
9
10CONTENTS
11
121. Background
132. Basic Operation
14 2-1. Mounting
15 2-2. cgroup.subtree_control
16 2-3. cgroup.controllers
173. Structural Constraints
18 3-1. Top-down
19 3-2. No internal tasks
204. 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
275. Planned Changes
28 5-1. CAP for resource control
29
30
311. Background
32
33cgroup allows an arbitrary number of hierarchies and each hierarchy
34can host any number of controllers. While this seems to provide a
35high level of flexibility, it isn't quite useful in practice.
36
37For example, as there is only one instance of each controller, utility
38type controllers such as freezer which can be useful in all
39hierarchies can only be used in one. The issue is exacerbated by the
40fact that controllers can't be moved around once hierarchies are
41populated. Another issue is that all controllers bound to a hierarchy
42are forced to have exactly the same view of the hierarchy. It isn't
43possible to vary the granularity depending on the specific controller.
44
45In practice, these issues heavily limit which controllers can be put
46on the same hierarchy and most configurations resort to putting each
47controller on its own hierarchy. Only closely related ones, such as
48the cpu and cpuacct controllers, make sense to put on the same
49hierarchy. This often means that userland ends up managing multiple
50similar hierarchies repeating the same steps on each hierarchy
51whenever a hierarchy management operation is necessary.
52
53Unfortunately, support for multiple hierarchies comes at a steep cost.
54Internal implementation in cgroup core proper is dazzlingly
55complicated but more importantly the support for multiple hierarchies
56restricts how cgroup is used in general and what controllers can do.
57
58There's no limit on how many hierarchies there may be, which means
59that a task's cgroup membership can't be described in finite length.
60The key may contain any varying number of entries and is unlimited in
61length, which makes it highly awkward to handle and leads to addition
62of controllers which exist only to identify membership, which in turn
63exacerbates the original problem.
64
65Also, as a controller can't have any expectation regarding what shape
66of hierarchies other controllers would be on, each controller has to
67assume that all other controllers are operating on completely
68orthogonal hierarchies. This makes it impossible, or at least very
69cumbersome, for controllers to cooperate with each other.
70
71In most use cases, putting controllers on hierarchies which are
72completely orthogonal to each other isn't necessary. What usually is
73called for is the ability to have differing levels of granularity
74depending on the specific controller. In other words, hierarchy may
75be collapsed from leaf towards root when viewed from specific
76controllers. For example, a given configuration might not care about
77how memory is distributed beyond a certain level while still wanting
78to control how CPU cycles are distributed.
79
80Unified hierarchy is the next version of cgroup interface. It aims to
81address the aforementioned issues by having more structure while
82retaining enough flexibility for most use cases. Various other
83general and controller-specific interface issues are also addressed in
84the process.
85
86
872. Basic Operation
88
892-1. Mounting
90
91Currently, unified hierarchy can be mounted with the following mount
92command. Note that this is still under development and scheduled to
93change soon.
94
95 mount -t cgroup -o __DEVEL__sane_behavior cgroup $MOUNT_POINT
96
Tejun Heoa8ddc822014-07-15 11:05:10 -040097All controllers which support the unified hierarchy and are not bound
98to other hierarchies are automatically bound to unified hierarchy and
99show up at the root of it. Controllers which are enabled only in the
100root of unified hierarchy can be bound to other hierarchies. This
101allows mixing unified hierarchy with the traditional multiple
102hierarchies in a fully backward compatible way.
103
104For development purposes, the following boot parameter makes all
105controllers to appear on the unified hierarchy whether supported or
106not.
107
108 cgroup__DEVEL__legacy_files_on_dfl
Tejun Heoaf0ba672014-07-08 18:02:57 -0400109
110A controller can be moved across hierarchies only after the controller
111is no longer referenced in its current hierarchy. Because per-cgroup
112controller states are destroyed asynchronously and controllers may
113have lingering references, a controller may not show up immediately on
114the unified hierarchy after the final umount of the previous
115hierarchy. Similarly, a controller should be fully disabled to be
116moved out of the unified hierarchy and it may take some time for the
117disabled controller to become available for other hierarchies;
118furthermore, due to dependencies among controllers, other controllers
119may need to be disabled too.
120
121While useful for development and manual configurations, dynamically
122moving controllers between the unified and other hierarchies is
123strongly discouraged for production use. It is recommended to decide
124the hierarchies and controller associations before starting using the
125controllers.
Tejun Heo65731572014-04-25 18:28:02 -0400126
127
1282-2. cgroup.subtree_control
129
130All cgroups on unified hierarchy have a "cgroup.subtree_control" file
131which governs which controllers are enabled on the children of the
132cgroup. Let's assume a hierarchy like the following.
133
134 root - A - B - C
135 \ D
136
137root's "cgroup.subtree_control" file determines which controllers are
138enabled on A. A's on B. B's on C and D. This coincides with the
139fact that controllers on the immediate sub-level are used to
140distribute the resources of the parent. In fact, it's natural to
141assume that resource control knobs of a child belong to its parent.
142Enabling a controller in a "cgroup.subtree_control" file declares that
143distribution of the respective resources of the cgroup will be
144controlled. Note that this means that controller enable states are
145shared among siblings.
146
147When read, the file contains a space-separated list of currently
148enabled controllers. A write to the file should contain a
149space-separated list of controllers with '+' or '-' prefixed (without
150the quotes). Controllers prefixed with '+' are enabled and '-'
151disabled. If a controller is listed multiple times, the last entry
152wins. The specific operations are executed atomically - either all
153succeed or fail.
154
155
1562-3. cgroup.controllers
157
158Read-only "cgroup.controllers" file contains a space-separated list of
159controllers which can be enabled in the cgroup's
160"cgroup.subtree_control" file.
161
162In the root cgroup, this lists controllers which are not bound to
163other hierarchies and the content changes as controllers are bound to
164and unbound from other hierarchies.
165
166In non-root cgroups, the content of this file equals that of the
167parent's "cgroup.subtree_control" file as only controllers enabled
168from the parent can be used in its children.
169
170
1713. Structural Constraints
172
1733-1. Top-down
174
175As it doesn't make sense to nest control of an uncontrolled resource,
176all non-root "cgroup.subtree_control" files can only contain
177controllers which are enabled in the parent's "cgroup.subtree_control"
178file. A controller can be enabled only if the parent has the
179controller enabled and a controller can't be disabled if one or more
180children have it enabled.
181
182
1833-2. No internal tasks
184
185One long-standing issue that cgroup faces is the competition between
186tasks belonging to the parent cgroup and its children cgroups. This
187is inherently nasty as two different types of entities compete and
188there is no agreed-upon obvious way to handle it. Different
189controllers are doing different things.
190
191The cpu controller considers tasks and cgroups as equivalents and maps
192nice levels to cgroup weights. This works for some cases but falls
193flat when children should be allocated specific ratios of CPU cycles
194and the number of internal tasks fluctuates - the ratios constantly
195change as the number of competing entities fluctuates. There also are
196other issues. The mapping from nice level to weight isn't obvious or
197universal, and there are various other knobs which simply aren't
198available for tasks.
199
200The blkio controller implicitly creates a hidden leaf node for each
201cgroup to host the tasks. The hidden leaf has its own copies of all
202the knobs with "leaf_" prefixed. While this allows equivalent control
203over internal tasks, it's with serious drawbacks. It always adds an
204extra layer of nesting which may not be necessary, makes the interface
205messy and significantly complicates the implementation.
206
207The memory controller currently doesn't have a way to control what
208happens between internal tasks and child cgroups and the behavior is
209not clearly defined. There have been attempts to add ad-hoc behaviors
210and knobs to tailor the behavior to specific workloads. Continuing
211this direction will lead to problems which will be extremely difficult
212to resolve in the long term.
213
214Multiple controllers struggle with internal tasks and came up with
215different ways to deal with it; unfortunately, all the approaches in
216use now are severely flawed and, furthermore, the widely different
217behaviors make cgroup as whole highly inconsistent.
218
219It is clear that this is something which needs to be addressed from
220cgroup core proper in a uniform way so that controllers don't need to
221worry about it and cgroup as a whole shows a consistent and logical
222behavior. To achieve that, unified hierarchy enforces the following
223structural constraint:
224
225 Except for the root, only cgroups which don't contain any task may
226 have controllers enabled in their "cgroup.subtree_control" files.
227
228Combined with other properties, this guarantees that, when a
229controller is looking at the part of the hierarchy which has it
230enabled, tasks are always only on the leaves. This rules out
231situations where child cgroups compete against internal tasks of the
232parent.
233
234There are two things to note. Firstly, the root cgroup is exempt from
235the restriction. Root contains tasks and anonymous resource
236consumption which can't be associated with any other cgroup and
237requires special treatment from most controllers. How resource
238consumption in the root cgroup is governed is up to each controller.
239
240Secondly, the restriction doesn't take effect if there is no enabled
241controller in the cgroup's "cgroup.subtree_control" file. This is
242important as otherwise it wouldn't be possible to create children of a
243populated cgroup. To control resource distribution of a cgroup, the
244cgroup must create children and transfer all its tasks to the children
245before enabling controllers in its "cgroup.subtree_control" file.
246
247
2484. Other Changes
249
2504-1. [Un]populated Notification
251
252cgroup users often need a way to determine when a cgroup's
253subhierarchy becomes empty so that it can be cleaned up. cgroup
254currently provides release_agent for it; unfortunately, this mechanism
255is riddled with issues.
256
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.
261
262- There is single monitoring point at the root. There's no way to
263 delegate management of a subtree.
264
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.
269
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.
274
275Unified hierarchy implements an interface file "cgroup.populated"
276which can be used to monitor whether the cgroup's subhierarchy has
277tasks in it or not. Its value is 0 if there is no task in the cgroup
278and its descendants; otherwise, 1. poll and [id]notify events are
279triggered when the value changes.
280
281This is significantly lighter and simpler and trivially allows
282delegating management of subhierarchy - subhierarchy monitoring can
283block further propagation simply by putting itself or another process
284in the subhierarchy and monitor events that it's interested in from
285there without interfering with monitoring higher in the tree.
286
287In unified hierarchy, the release_agent mechanism is no longer
288supported and the interface files "release_agent" and
289"notify_on_release" do not exist.
290
291
2924-2. Other Core Changes
293
294- None of the mount options is allowed.
295
296- remount is disallowed.
297
298- rename(2) is disallowed.
299
300- The "tasks" file is removed. Everything should at process
301 granularity. Use the "cgroup.procs" file instead.
302
303- The "cgroup.procs" file is not sorted. pids will be unique unless
304 they got recycled in-between reads.
305
306- The "cgroup.clone_children" file is removed.
307
308
3094-3. Per-Controller Changes
310
3114-3-1. blkio
312
313- blk-throttle becomes properly hierarchical.
314
315
3164-3-2. cpuset
317
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.
320
321- A task can be moved into an empty cpuset, and again it takes on the
322 masks of the nearest non-empty ancestor.
323
324
3254-3-3. memory
326
327- use_hierarchy is on by default and the cgroup file for the flag is
328 not created.
329
Johannes Weiner241994e2015-02-11 15:26:06 -0800330- The original lower boundary, the soft limit, is defined as a limit
331 that is per default unset. As a result, the set of cgroups that
332 global reclaim prefers is opt-in, rather than opt-out. The costs
333 for optimizing these mostly negative lookups are so high that the
334 implementation, despite its enormous size, does not even provide the
335 basic desirable behavior. First off, the soft limit has no
336 hierarchical meaning. All configured groups are organized in a
337 global rbtree and treated like equal peers, regardless where they
338 are located in the hierarchy. This makes subtree delegation
339 impossible. Second, the soft limit reclaim pass is so aggressive
340 that it not just introduces high allocation latencies into the
341 system, but also impacts system performance due to overreclaim, to
342 the point where the feature becomes self-defeating.
343
344 The memory.low boundary on the other hand is a top-down allocated
345 reserve. A cgroup enjoys reclaim protection when it and all its
346 ancestors are below their low boundaries, which makes delegation of
347 subtrees possible. Secondly, new cgroups have no reserve per
348 default and in the common case most cgroups are eligible for the
349 preferred reclaim pass. This allows the new low boundary to be
350 efficiently implemented with just a minor addition to the generic
351 reclaim code, without the need for out-of-band data structures and
352 reclaim passes. Because the generic reclaim code considers all
353 cgroups except for the ones running low in the preferred first
354 reclaim pass, overreclaim of individual groups is eliminated as
355 well, resulting in much better overall workload performance.
356
357- The original high boundary, the hard limit, is defined as a strict
358 limit that can not budge, even if the OOM killer has to be called.
359 But this generally goes against the goal of making the most out of
360 the available memory. The memory consumption of workloads varies
361 during runtime, and that requires users to overcommit. But doing
362 that with a strict upper limit requires either a fairly accurate
363 prediction of the working set size or adding slack to the limit.
364 Since working set size estimation is hard and error prone, and
365 getting it wrong results in OOM kills, most users tend to err on the
366 side of a looser limit and end up wasting precious resources.
367
368 The memory.high boundary on the other hand can be set much more
369 conservatively. When hit, it throttles allocations by forcing them
370 into direct reclaim to work off the excess, but it never invokes the
371 OOM killer. As a result, a high boundary that is chosen too
372 aggressively will not terminate the processes, but instead it will
373 lead to gradual performance degradation. The user can monitor this
374 and make corrections until the minimal memory footprint that still
375 gives acceptable performance is found.
376
377 In extreme cases, with many concurrent allocations and a complete
378 breakdown of reclaim progress within the group, the high boundary
379 can be exceeded. But even then it's mostly better to satisfy the
380 allocation from the slack available in other groups or the rest of
381 the system than killing the group. Otherwise, memory.max is there
382 to limit this type of spillover and ultimately contain buggy or even
383 malicious applications.
384
385- The original control file names are unwieldy and inconsistent in
386 many different ways. For example, the upper boundary hit count is
387 exported in the memory.failcnt file, but an OOM event count has to
388 be manually counted by listening to memory.oom_control events, and
389 lower boundary / soft limit events have to be counted by first
390 setting a threshold for that value and then counting those events.
391 Also, usage and limit files encode their units in the filename.
392 That makes the filenames very long, even though this is not
393 information that a user needs to be reminded of every time they type
394 out those names.
395
396 To address these naming issues, as well as to signal clearly that
397 the new interface carries a new configuration model, the naming
398 conventions in it necessarily differ from the old interface.
399
400- The original limit files indicate the state of an unset limit with a
401 Very High Number, and a configured limit can be unset by echoing -1
402 into those files. But that very high number is implementation and
403 architecture dependent and not very descriptive. And while -1 can
404 be understood as an underflow into the highest possible value, -2 or
405 -10M etc. do not work, so it's not consistent.
406
407 memory.low, memory.high, and memory.max will use the string
408 "infinity" to indicate and set the highest possible value.
Tejun Heo65731572014-04-25 18:28:02 -0400409
4105. Planned Changes
411
4125-1. CAP for resource control
413
414Unified hierarchy will require one of the capabilities(7), which is
415yet to be decided, for all resource control related knobs. Process
416organization operations - creation of sub-cgroups and migration of
417processes in sub-hierarchies may be delegated by changing the
418ownership and/or permissions on the cgroup directory and
419"cgroup.procs" interface file; however, all operations which affect
420resource control - writes to a "cgroup.subtree_control" file or any
421controller-specific knobs - will require an explicit CAP privilege.
422
423This, in part, is to prevent the cgroup interface from being
424inadvertently promoted to programmable API used by non-privileged
425binaries. cgroup exposes various aspects of the system in ways which
426aren't properly abstracted for direct consumption by regular programs.
427This is an administration interface much closer to sysctl knobs than
428system calls. Even the basic access model, being filesystem path
429based, isn't suitable for direct consumption. There's no way to
430access "my cgroup" in a race-free way or make multiple operations
431atomic against migration to another cgroup.
432
433Another aspect is that, for better or for worse, the cgroup interface
434goes through far less scrutiny than regular interfaces for
435unprivileged userland. The upside is that cgroup is able to expose
436useful features which may not be suitable for general consumption in a
437reasonable time frame. It provides a relatively short path between
438internal details and userland-visible interface. Of course, this
439shortcut comes with high risk. We go through what we go through for
440general kernel APIs for good reasons. It may end up leaking internal
441details in a way which can exert significant pain by locking the
442kernel into a contract that can't be maintained in a reasonable
443manner.
444
445Also, due to the specific nature, cgroup and its controllers don't
446tend to attract attention from a wide scope of developers. cgroup's
447short history is already fraught with severely mis-designed
448interfaces, unnecessary commitments to and exposing of internal
449details, broken and dangerous implementations of various features.
450
451Keeping cgroup as an administration interface is both advantageous for
452its role and imperative given its nature. Some of the cgroup features
453may make sense for unprivileged access. If deemed justified, those
454must be further abstracted and implemented as a different interface,
455be it a system call or process-private filesystem, and survive through
456the scrutiny that any interface for general consumption is required to
457go through.
458
459Requiring CAP is not a complete solution but should serve as a
460significant deterrent against spraying cgroup usages in non-privileged
461programs.