Based on kernel version 4.1. Page generated on 2015-06-28 12:08 EST.
1 2 Cgroup unified hierarchy 3 4 April, 2014 Tejun Heo <email@example.com> 5 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. 9 10 CONTENTS 11 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 29 30 31 1. Background 32 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. 36 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. 44 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. 52 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. 57 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. 64 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. 70 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. 79 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. 85 86 87 2. Basic Operation 88 89 2-1. Mounting 90 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. 94 95 mount -t cgroup -o __DEVEL__sane_behavior cgroup $MOUNT_POINT 96 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. 103 104 For development purposes, the following boot parameter makes all 105 controllers to appear on the unified hierarchy whether supported or 106 not. 107 108 cgroup__DEVEL__legacy_files_on_dfl 109 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. 120 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. 126 127 128 2-2. cgroup.subtree_control 129 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. 133 134 root - A - B - C 135 \ D 136 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. 146 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. 154 155 156 2-3. cgroup.controllers 157 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. 161 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. 165 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. 169 170 171 3. Structural Constraints 172 173 3-1. Top-down 174 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. 181 182 183 3-2. No internal tasks 184 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. 190 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. 199 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. 206 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. 213 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. 218 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: 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 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. 233 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. 239 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. 246 247 248 4. Other Changes 249 250 4-1. [Un]populated Notification 251 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. 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 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. 280 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. 286 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. 290 291 292 4-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 309 4-3. Per-Controller Changes 310 311 4-3-1. blkio 312 313 - blk-throttle becomes properly hierarchical. 314 315 316 4-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 325 4-3-3. memory 326 327 - use_hierarchy is on by default and the cgroup file for the flag is 328 not created. 329 330 - 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 "max" to 408 indicate and set the highest possible value. 409 410 5. Planned Changes 411 412 5-1. CAP for resource control 413 414 Unified hierarchy will require one of the capabilities(7), which is 415 yet to be decided, for all resource control related knobs. Process 416 organization operations - creation of sub-cgroups and migration of 417 processes in sub-hierarchies may be delegated by changing the 418 ownership and/or permissions on the cgroup directory and 419 "cgroup.procs" interface file; however, all operations which affect 420 resource control - writes to a "cgroup.subtree_control" file or any 421 controller-specific knobs - will require an explicit CAP privilege. 422 423 This, in part, is to prevent the cgroup interface from being 424 inadvertently promoted to programmable API used by non-privileged 425 binaries. cgroup exposes various aspects of the system in ways which 426 aren't properly abstracted for direct consumption by regular programs. 427 This is an administration interface much closer to sysctl knobs than 428 system calls. Even the basic access model, being filesystem path 429 based, isn't suitable for direct consumption. There's no way to 430 access "my cgroup" in a race-free way or make multiple operations 431 atomic against migration to another cgroup. 432 433 Another aspect is that, for better or for worse, the cgroup interface 434 goes through far less scrutiny than regular interfaces for 435 unprivileged userland. The upside is that cgroup is able to expose 436 useful features which may not be suitable for general consumption in a 437 reasonable time frame. It provides a relatively short path between 438 internal details and userland-visible interface. Of course, this 439 shortcut comes with high risk. We go through what we go through for 440 general kernel APIs for good reasons. It may end up leaking internal 441 details in a way which can exert significant pain by locking the 442 kernel into a contract that can't be maintained in a reasonable 443 manner. 444 445 Also, due to the specific nature, cgroup and its controllers don't 446 tend to attract attention from a wide scope of developers. cgroup's 447 short history is already fraught with severely mis-designed 448 interfaces, unnecessary commitments to and exposing of internal 449 details, broken and dangerous implementations of various features. 450 451 Keeping cgroup as an administration interface is both advantageous for 452 its role and imperative given its nature. Some of the cgroup features 453 may make sense for unprivileged access. If deemed justified, those 454 must be further abstracted and implemented as a different interface, 455 be it a system call or process-private filesystem, and survive through 456 the scrutiny that any interface for general consumption is required to 457 go through. 458 459 Requiring CAP is not a complete solution but should serve as a 460 significant deterrent against spraying cgroup usages in non-privileged 461 programs.