Control Groups

Control group 정의와 기본 모델

이 문서는 Paul Menage `<menage@google.com>`가 `Documentation/admin-guide/cgroup-v1/cpusets.rst`를 바탕으로 작성했습니다. 원 cpusets 문서에는 BULL SA(2004), Silicon Graphics(2004-2006)의 copyright와 Paul Jackson·Christoph Lameter의 수정 기록이 있습니다.

Control Group은 task 집합과 앞으로 생길 child를 specialized behavior가 있는 hierarchical group으로 aggregate·partition하는 mechanism입니다.

System에는 여러 active task-cgroup hierarchy가 동시에 존재할 수 있으며 각각 전체 task의 partition입니다. User-space는 cgroup virtual filesystem instance에서 name으로 cgroup을 만들고 지우며, task assignment를 지정·조회하고 cgroup별 PID를 열거합니다. 이 조작은 해당 filesystem instance의 hierarchy에만 영향을 줍니다.

Cgroup 자체만으로는 단순 job tracking 정도에 쓰입니다. 다른 subsystem이 generic cgroup support에 hook해 accounting·resource limit 같은 새 attribute를 제공합니다. 예를 들어 cpuset은 각 cgroup task에 CPU 집합과 memory-node 집합을 연결합니다.

Cgroup 필요성과 multiple hierarchy

Linux kernel에는 cpuset, CKRM/ResGroups, UserBeanCounters, virtual-server namespace처럼 resource tracking을 위한 process aggregation 시도가 여러 개 있었습니다. 모두 새 fork process가 parent와 같은 group에 들어가는 process grouping·partitioning 개념이 필요합니다.

Kernel cgroup patch는 이런 group을 효율적으로 구현하는 최소 mechanism을 제공하고 fast path 영향은 최소화하며 cpuset 같은 subsystem이 필요한 behavior를 추가할 hook을 제공합니다.

Subsystem마다 task division이 크게 다를 수 있으므로 multiple hierarchy를 지원합니다. 서로 무관한 controller를 한 tree에 강제해 복잡한 task 조합을 만드는 대신 각 hierarchy가 자연스러운 partition을 표현합니다. 극단적으로 controller마다 별도 hierarchy를 두거나 모든 subsystem을 한 hierarchy에 붙일 수 있습니다.

University server 예제는 CPU, memory, disk, network를 서로 다르게 분할합니다. CPU는 professor와 student cpuset으로 나누고 system task는 어디서나 실행하되 20% limit을 둡니다. Memory와 disk는 professor 50%, student 30%, system 20%입니다. Network는 WWW 20%, NFS 60%, 기타 20%이고 WWW 안에서 professor 15%, student 5%입니다.

As an example of a scenario (originally proposed by vatsa@in.ibm.com)
that can benefit from multiple hierarchies, consider a large
university server with various users - students, professors, system
tasks etc. The resource planning for this server could be along the
following lines::

       CPU :          "Top cpuset"
                       /       \
               CPUSet1         CPUSet2
                  |               |
               (Professors)    (Students)

               In addition (system tasks) are attached to topcpuset (so
               that they can run anywhere) with a limit of 20%

       Memory : Professors (50%), Students (30%), system (20%)

       Disk : Professors (50%), Students (30%), system (20%)

       Network : WWW browsing (20%), Network File System (60%), others (20%)
                               / \
               Professors (15%)  students (5%)

Browsers like Firefox/Lynx go into the WWW network class, while (k)nfsd goes
into the NFS network class.

Firefox/Lynx는 WWW network class에, `(k)nfsd`는 NFS class에 들어갑니다. 동시에 browser는 실행한 사람이 professor인지 student인지에 따라 적절한 CPU·memory class를 공유합니다.

Resource subsystem을 다른 hierarchy에 두면 administrator script가 exec notification을 받아 launcher에 따라 browser PID를 해당 resource/user class의 `tasks` file에 쓸 수 있습니다. 단일 hierarchy만 있으면 browser마다 별도 cgroup을 만들고 network와 다른 resource class 조합을 연결해야 해 cgroup이 급증할 수 있습니다.

With the ability to classify tasks differently for different resources
(by putting those resource subsystems in different hierarchies),
the admin can easily set up a script which receives exec notifications
and depending on who is launching the browser he can::

    # echo browser_pid > /sys/fs/cgroup/<restype>/<userclass>/tasks

With only a single hierarchy, he now would potentially have to create
a separate cgroup for every browser launched and associate it with
appropriate network and other resource class.  This may lead to
proliferation of such cgroups.

Student browser에 일시적으로 더 많은 network를 주거나 simulation app에 더 많은 CPU를 주려면 PID를 새 resource class로 옮겼다가 원래 class로 돌리면 됩니다. 이 기능이 없으면 cgroup을 여러 개로 split하고 새 resource class와 연결해야 합니다.

Also let's say that the administrator would like to give enhanced network
access temporarily to a student's browser (since it is night and the user
wants to do online gaming :))  OR give one of the student's simulation
apps enhanced CPU power.

With ability to write PIDs directly to resource classes, it's just a
matter of::

       # echo pid > /sys/fs/cgroup/network/<new_class>/tasks
       (after some time)
       # echo pid > /sys/fs/cgroup/network/<orig_class>/tasks

Without this ability, the administrator would have to split the cgroup into
multiple separate ones and then associate the new cgroups with the
new resource classes.

Kernel 구현과 filesystem representation

각 task는 reference-counted `css_set` pointer를 갖습니다. `css_set`은 등록된 cgroup subsystem마다 하나씩 reference-counted `cgroup_subsys_state` pointer 집합을 가집니다.

Task에서 각 hierarchy의 cgroup으로 직접 가는 link는 없고 subsystem-state pointer를 따라 assignment를 찾습니다. Performance-critical code에서는 subsystem state를 자주 접근하지만 실제 cgroup assignment와 move는 드물기 때문입니다. 각 `task_struct`의 `cg_list`를 잇는 linked list가 `css_set->tasks`에 anchor됩니다.

User space는 mounted cgroup hierarchy filesystem을 browse·manipulate하고 어느 cgroup에 붙은 task PID도 열거할 수 있습니다. Kernel hook은 root cgroup·initial css_set boot initialization(`init/main.c`)과 fork/exit의 css_set attach/detach 정도이며 performance-critical path에는 없습니다.

`cgroup` type filesystem mount option에 comma-separated subsystem 목록을 지정합니다. 생략하면 등록된 모든 subsystem을 포함하려고 합니다. 같은 subsystem set의 active hierarchy가 있으면 새 mount가 reuse합니다. 일치하는 hierarchy가 없고 요청 subsystem 중 하나가 다른 hierarchy에서 사용 중이면 `-EBUSY`로 실패하며, 아니면 새 hierarchy를 활성화합니다.

현재 active hierarchy에 새 subsystem을 bind하거나 unbind할 수 없습니다. Error recovery가 어렵기 때문입니다. Filesystem을 unmount할 때 top-level 아래 child cgroup이 있으면 hierarchy는 unmounted 상태로 active를 유지하고, child가 없으면 deactivate됩니다.

Cgroup은 새 system call을 추가하지 않으며 query·modify는 모두 cgroup filesystem을 통합니다. `/proc/<task>/cgroup`은 active hierarchy마다 subsystem name과 filesystem root 기준 cgroup path를 표시합니다.

Cpuset 같은 subsystem은 각 directory에 file을 추가할 수 있습니다. `mkdir`로 새 cgroup을 만들고 해당 file에 써 flag·property를 바꿉니다. Nested named tree는 큰 system을 동적으로 바뀌는 soft partition으로 나눕니다.

Task의 cgroup attachment는 fork child가 자동 상속하며 permission이 허용하면 다른 cgroup으로 옮길 수 있습니다. Move 시 원하는 cgroup 조합의 기존 `css_set`을 hash table에서 찾아 reuse하거나 새로 allocate해 task pointer를 바꿉니다.

Cgroup에서 구성 `css_set`과 task에 접근하도록 `cg_cgroup_link` lattice를 사용합니다. Link는 한 cgroup의 `cgrp_link_list`와 한 css_set의 `cg_link_list` 양쪽에 연결됩니다. Cgroup task 목록은 해당 cgroup을 참조하는 css_set을 순회하고 각 css_set task set을 다시 순회해 얻습니다. VFS 표현은 익숙한 permission·namespace를 최소 kernel code로 제공합니다.

Release notification·clone_children·cpuset job

Cgroup에서 `notify_on_release=1`이면 마지막 task가 exit하거나 다른 cgroup으로 이동하고 마지막 child cgroup도 제거될 때 kernel이 hierarchy root의 `release_agent` command를 실행합니다. Mount point 기준 abandoned cgroup relative path를 argument로 넘겨 자동 제거를 가능하게 합니다.

Boot 시 root cgroup의 `notify_on_release` default는 0입니다. 새 child cgroup은 생성 시 parent의 현재 setting을 상속합니다. Hierarchy의 `release_agent` path default는 empty입니다.

`clone_children`은 cpuset controller에만 영향을 줍니다. Parent cgroup에서 1이면 새 cpuset cgroup이 initialization 때 parent configuration을 copy합니다.

Cpuset cgroup 안에서 새 job을 시작하려면 tmpfs와 cpuset hierarchy를 mount하고, directory/file write로 cgroup을 만들고, founding task를 시작해 PID를 `tasks`에 쓴 뒤 그 task에서 job process를 fork·exec·clone합니다.

1.6 How do I use cgroups ?
--------------------------

To start a new job that is to be contained within a cgroup, using
the "cpuset" cgroup subsystem, the steps are something like::

 1) mount -t tmpfs cgroup_root /sys/fs/cgroup
 2) mkdir /sys/fs/cgroup/cpuset
 3) mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset
 4) Create the new cgroup by doing mkdir's and write's (or echo's) in
    the /sys/fs/cgroup/cpuset virtual file system.
 5) Start a task that will be the "founding father" of the new job.
 6) Attach that task to the new cgroup by writing its PID to the
    /sys/fs/cgroup/cpuset tasks file for that cgroup.
 7) fork, exec or clone the job tasks from this founding father task.

예제는 CPU 2-3과 memory node 1만 갖는 `Charlie` cgroup을 만들고 현재 shell을 붙인 뒤 subshell을 시작합니다. `/proc/self/cgroup`은 `/Charlie`를 보여야 합니다.

For example, the following sequence of commands will setup a cgroup
named "Charlie", containing just CPUs 2 and 3, and Memory Node 1,
and then start a subshell 'sh' in that cgroup::

  mount -t tmpfs cgroup_root /sys/fs/cgroup
  mkdir /sys/fs/cgroup/cpuset
  mount -t cgroup cpuset -ocpuset /sys/fs/cgroup/cpuset
  cd /sys/fs/cgroup/cpuset
  mkdir Charlie
  cd Charlie
  /bin/echo 2-3 > cpuset.cpus
  /bin/echo 1 > cpuset.mems
  /bin/echo $$ > tasks
  sh
  # The subshell 'sh' is now running in cgroup Charlie
  # The next line should display '/Charlie'
  cat /proc/self/cgroup

Filesystem mount와 cgroup lifecycle

Cgroup 생성·수정·사용은 virtual filesystem으로 수행합니다. 모든 available subsystem hierarchy를 mount할 때 source 이름 `xxx`는 cgroup code가 해석하지 않으며 `/proc/mounts`에 표시되는 식별 문자열일 뿐입니다.

Creating, modifying, using cgroups can be done through the cgroup
virtual filesystem.

To mount a cgroup hierarchy with all available subsystems, type::

  # mount -t cgroup xxx /sys/fs/cgroup

The "xxx" is not interpreted by the cgroup code, but will appear in
/proc/mounts so may be any useful identifying string that you like.

일부 subsystem은 먼저 user input이 필요합니다. 예를 들어 cpuset은 새 cgroup을 사용하기 전에 `cpus`와 `mems` file을 채워야 합니다. Resource 또는 resource group마다 별도 hierarchy를 만들기 위해 `/sys/fs/cgroup`에 tmpfs를 mount하고 directory를 만듭니다.

Note: Some subsystems do not work without some user input first.  For instance,
if cpusets are enabled the user will have to populate the cpus and mems files
for each new cgroup created before that group can be used.

As explained in section `1.2 Why are cgroups needed?` you should create
different hierarchies of cgroups for each single resource or group of
resources you want to control. Therefore, you should mount a tmpfs on
/sys/fs/cgroup and create directories for each cgroup resource or resource
group::

  # mount -t tmpfs cgroup_root /sys/fs/cgroup
  # mkdir /sys/fs/cgroup/rg1

To mount a cgroup hierarchy with just the cpuset and memory
subsystems, type::

  # mount -t cgroup -o cpuset,memory hier1 /sys/fs/cgroup/rg1

Cpuset과 memory만 포함하는 hierarchy는 `-o cpuset,memory`로 mount합니다. Remount는 지원되지만 권장하지 않습니다. Bound subsystem과 release_agent를 바꿀 수 있으나 rebinding은 empty hierarchy에서만 되고 release_agent는 fsnotify로 대체해야 하므로 remount support는 미래에 제거될 예정입니다.

Mount option으로 `release_agent` path를 지정할 수 있지만 두 번 이상 지정하면 실패합니다. Subsystem set 변경은 hierarchy가 root cgroup 하나로만 구성될 때만 지원됩니다.

To Specify a hierarchy's release_agent::

  # mount -t cgroup -o cpuset,release_agent="/sbin/cpuset_release_agent" \
    xxx /sys/fs/cgroup/rg1

Note that specifying 'release_agent' more than once will return failure.

Note that changing the set of subsystems is currently only supported
when the hierarchy consists of a single (root) cgroup. Supporting
the ability to arbitrarily bind/unbind subsystems from an existing
cgroup hierarchy is intended to be implemented in the future.

Mount point 아래 tree가 system cgroup tree와 대응하며 mount root는 system 전체를 담습니다. `release_agent` file에 새 path를 써 값을 바꾸거나 remount로 변경할 수 있습니다.

Then under /sys/fs/cgroup/rg1 you can find a tree that corresponds to the
tree of the cgroups in the system. For instance, /sys/fs/cgroup/rg1
is the cgroup that holds the whole system.

If you want to change the value of release_agent::

  # echo "/sbin/new_release_agent" > /sys/fs/cgroup/rg1/release_agent

It can also be changed via remount.

`mkdir my_cgroup`으로 child를 만들고 directory의 generic·subsystem file을 사용합니다. 현재 shell의 PID `$$`를 `tasks`에 써 attach하고 안에서 다시 `mkdir`해 nested cgroup을 만들 수 있습니다.

If you want to create a new cgroup under /sys/fs/cgroup/rg1::

  # cd /sys/fs/cgroup/rg1
  # mkdir my_cgroup

Now you want to do something with this cgroup:

  # cd my_cgroup

In this directory you can find several files::

  # ls
  cgroup.procs notify_on_release tasks
  (plus whatever files added by the attached subsystems)

Now attach your shell to this cgroup::

  # /bin/echo $$ > tasks

You can also create cgroups inside your cgroup by using mkdir in this
directory::

  # mkdir my_sub_cs

`rmdir`로 cgroup을 제거합니다. Child cgroup이나 attached process가 있거나 subsystem-specific reference가 살아 있으면 실패합니다.

To remove a cgroup, just use rmdir::

  # rmdir my_sub_cs

This will fail if the cgroup is in use (has cgroups inside, or
has processes attached, or is held alive by other subsystem-specific
reference).

Process attach와 named hierarchy

`tasks`에는 PID 하나만 쓸 수 있습니다. 여러 task를 붙이려면 한 번에 하나씩 각각 write합니다. 현재 shell task는 0을 써 attach할 수 있습니다.

::

  # /bin/echo PID > tasks

Note that it is PID, not PIDs. You can only attach ONE task at a time.
If you have several tasks to attach, you have to do it one after another::

  # /bin/echo PID1 > tasks
  # /bin/echo PID2 > tasks
	  ...
  # /bin/echo PIDn > tasks

You can attach the current shell task by echoing 0::

  # echo 0 > tasks

`cgroup.procs`에 thread group의 어느 task PID를 써도 group의 모든 thread를 이동합니다. 모든 task는 mounted hierarchy마다 정확히 한 cgroup의 member이므로 현재 cgroup에서 제거한다는 것은 새 cgroup, 필요하면 root cgroup의 `tasks` file에 써서 이동하는 것입니다. Subsystem restriction 때문에 move가 실패할 수 있습니다.

Hierarchy mount에 `name=<x>`를 넘기면 이름을 연결합니다. 기존 hierarchy를 active subsystem set 대신 name으로 mount할 때 유용합니다. Hierarchy는 nameless이거나 unique name 하나를 가지며 name은 `[\w.-]+`와 일치해야 합니다.

새 named hierarchy에는 subsystem을 직접 지정해야 합니다. Name을 주면서 subsystem을 생략했을 때 모든 subsystem을 mount하는 legacy behavior는 지원하지 않습니다. Hierarchy name은 `/proc/mounts`와 `/proc/<pid>/cgroups` description에 나타납니다.

Kernel API object와 synchronization

Generic cgroup system에 hook할 kernel subsystem은 `cgroup_subsys` object를 만듭니다. 이 object에는 cgroup callback method와 cgroup system이 할당하는 subsystem ID가 들어 있습니다.

각 cgroup object는 subsystem ID로 index한 pointer array를 갖습니다. 해당 pointer는 subsystem이 완전히 관리하며 generic cgroup code는 건드리지 않습니다.

Global `cgroup_mutex`는 cgroup 수정 시 반드시 잡습니다. 수정 방지 목적으로도 사용할 수 있지만 더 구체적인 lock이 적절할 수 있습니다. 자세한 내용은 `kernel/cgroup.c`에 있으며 subsystem은 `cgroup_lock()`·`cgroup_unlock()`으로 mutex를 잡고 풉니다.

Subsystem 등록과 css lifecycle callback

각 subsystem은 `linux/cgroup_subsys.h`에 entry를 추가하고 `<name>_cgrp_subsys`라는 `cgroup_subsys` object를 정의합니다. `css_alloc`·`css_free`만 mandatory이며 null인 다른 method는 성공하는 no-op으로 간주합니다.

`css_alloc()` caller는 `cgroup_mutex`를 잡고 있습니다. Subsystem-specific object 안에 보통 embed된 `cgroup_subsys_state`를 allocate해 반환하고 cgroup core가 initialize합니다. Root cgroup은 parent가 NULL이므로 subsystem root initialization을 수행할 수 있습니다.

`css_online()`은 모든 allocation이 끝나고 `cgroup_for_each_child/descendant_*()` iterator에 visible해진 뒤 호출합니다. Error를 반환해 creation을 실패시킬 수 있으며 hierarchy의 reliable state sharing·propagation에 사용할 수 있습니다. Creation과 destruction race를 피해야 하는 경우에는 `cgroup_for_each_live_descendant_pre()`를 사용합니다.

`css_offline()`은 online의 counterpart로 removal 시작을 알리고 subsystem이 가진 reference를 drop하게 합니다. 모두 사라지면 `css_free()`로 진행합니다. `css_free()` 시점에는 cgroup이 완전히 unused이고 parent는 아직 valid합니다.

Task attach·reset callback

`can_attach(cgrp, tset)`은 하나 이상의 task를 cgroup으로 옮기기 전에 호출합니다. Error를 반환하면 attach를 중단합니다. 여러 task라면 모두 같은 thread group이고, 이동 여부와 관계없이 group의 모든 task가 포함되며 첫 task가 leader입니다.

각 taskset entry에는 old cgroup도 들어 있습니다. `cgroup_taskset_for_each()`로 실제로 이동하지 않는 task를 건너뛸 수 있습니다. Fork에서는 호출하지 않습니다. 0을 반환하면 caller가 `cgroup_mutex`를 잡는 동안 결과가 valid하며 이후 `attach()` 또는 `cancel_attach()` 중 하나가 호출됩니다.

`css_reset(css)`는 optional callback으로 configuration을 initial state로 되돌립니다. Unified hierarchy의 `cgroup.subtree_control`에서 disable됐지만 다른 subsystem dependency 때문에 실제 disable할 수 없는 hidden subsystem에 사용합니다. Core가 interface file을 제거해 css를 invisible하게 하고 reset을 호출해 neutral state로 만들어 hidden resource control을 막고, 나중에 다시 visible할 때 초기 configuration을 보장합니다.

`cancel_attach()`는 successful `can_attach()` 뒤 전체 attach가 실패했을 때 같은 parameter로 호출합니다. Side effect가 있는 subsystem만 rollback을 구현하면 됩니다. `attach()`는 task 이동 뒤 memory allocation이나 blocking이 필요한 post-attachment 작업을 수행합니다.

Task event와 hierarchy bind callback

`fork(task)`는 task가 cgroup 안에서 fork될 때, `exit(task)`는 task exit 중, `free(task)`는 `task_struct`를 free할 때 호출합니다.

`bind(root)`는 cgroup subsystem이 다른 hierarchy와 root cgroup으로 rebind될 때 호출하며 caller가 `cgroup_mutex`를 잡습니다. 현재는 sub-cgroup이 절대 없는 default hierarchy와 생성·삭제 중이라 sub-cgroup이 없는 hierarchy 사이의 이동만 포함합니다.

Cgroup filesystem extended attribute

Cgroup filesystem directory와 file은 Trusted(`XATTR_TRUSTED`)와 Security(`XATTR_SECURITY`) extended attribute를 지원합니다. 둘 다 set하려면 `CAP_SYS_ADMIN` capability가 필요합니다.

Tmpfs처럼 xattr은 kernel memory에 저장되므로 사용량을 최소화하는 것이 좋습니다. 누구나 만들 수 있고 value-size limit이 없는 user-defined xattr은 지원하지 않습니다.

알려진 사용자는 container의 cgroup 사용을 제한하는 SELinux와 service마다 cgroup을 만들고 main PID 같은 metadata를 저장하는 systemd입니다.

자주 묻는 질문

예제에서 `/bin/echo`를 쓰는 이유는 Bash builtin `echo`가 `write()` error를 검사하지 않기 때문입니다. Builtin을 cgroup filesystem에 쓰면 command 성공·실패를 알 수 없습니다.

여러 PID를 한 줄에 써도 첫 task만 attach되는 이유는 `write()` 호출 하나당 error code 하나만 반환할 수 있기 때문입니다. 한 번에 PID 하나만 써야 합니다.