README.md
1# cgroups
2
3[](https://github.com/containerd/cgroups/actions?query=workflow%3ACI)
4[](https://codecov.io/gh/containerd/cgroups)
5[](https://godoc.org/github.com/containerd/cgroups)
6[](https://goreportcard.com/report/github.com/containerd/cgroups)
7
8Go package for creating, managing, inspecting, and destroying cgroups.
9The resources format for settings on the cgroup uses the OCI runtime-spec found
10[here](https://github.com/opencontainers/runtime-spec).
11
12## Examples
13
14### Create a new cgroup
15
16This creates a new cgroup using a static path for all subsystems under `/test`.
17
18* /sys/fs/cgroup/cpu/test
19* /sys/fs/cgroup/memory/test
20* etc....
21
22It uses a single hierarchy and specifies cpu shares as a resource constraint and
23uses the v1 implementation of cgroups.
24
25
26```go
27shares := uint64(100)
28control, err := cgroups.New(cgroups.V1, cgroups.StaticPath("/test"), &specs.LinuxResources{
29 CPU: &specs.CPU{
30 Shares: &shares,
31 },
32})
33defer control.Delete()
34```
35
36### Create with systemd slice support
37
38
39```go
40control, err := cgroups.New(cgroups.Systemd, cgroups.Slice("system.slice", "runc-test"), &specs.LinuxResources{
41 CPU: &specs.CPU{
42 Shares: &shares,
43 },
44})
45
46```
47
48### Load an existing cgroup
49
50```go
51control, err = cgroups.Load(cgroups.V1, cgroups.StaticPath("/test"))
52```
53
54### Add a process to the cgroup
55
56```go
57if err := control.Add(cgroups.Process{Pid:1234}); err != nil {
58}
59```
60
61### Update the cgroup
62
63To update the resources applied in the cgroup
64
65```go
66shares = uint64(200)
67if err := control.Update(&specs.LinuxResources{
68 CPU: &specs.LinuxCPU{
69 Shares: &shares,
70 },
71}); err != nil {
72}
73```
74
75### Freeze and Thaw the cgroup
76
77```go
78if err := control.Freeze(); err != nil {
79}
80if err := control.Thaw(); err != nil {
81}
82```
83
84### List all processes in the cgroup or recursively
85
86```go
87processes, err := control.Processes(cgroups.Devices, recursive)
88```
89
90### Get Stats on the cgroup
91
92```go
93stats, err := control.Stat()
94```
95
96By adding `cgroups.IgnoreNotExist` all non-existent files will be ignored, e.g. swap memory stats without swap enabled
97```go
98stats, err := control.Stat(cgroups.IgnoreNotExist)
99```
100
101### Move process across cgroups
102
103This allows you to take processes from one cgroup and move them to another.
104
105```go
106err := control.MoveTo(destination)
107```
108
109### Create subcgroup
110
111```go
112subCgroup, err := control.New("child", resources)
113```
114
115### Registering for memory events
116
117This allows you to get notified by an eventfd for v1 memory cgroups events.
118
119```go
120event := cgroups.MemoryThresholdEvent(50 * 1024 * 1024, false)
121efd, err := control.RegisterMemoryEvent(event)
122```
123
124```go
125event := cgroups.MemoryPressureEvent(cgroups.MediumPressure, cgroups.DefaultMode)
126efd, err := control.RegisterMemoryEvent(event)
127```
128
129```go
130efd, err := control.OOMEventFD()
131// or by using RegisterMemoryEvent
132event := cgroups.OOMEvent()
133efd, err := control.RegisterMemoryEvent(event)
134```
135
136### Attention
137
138All static path should not include `/sys/fs/cgroup/` prefix, it should start with your own cgroups name
139
140## Project details
141
142Cgroups is a containerd sub-project, licensed under the [Apache 2.0 license](./LICENSE).
143As a containerd sub-project, you will find the:
144
145 * [Project governance](https://github.com/containerd/project/blob/master/GOVERNANCE.md),
146 * [Maintainers](https://github.com/containerd/project/blob/master/MAINTAINERS),
147 * and [Contributing guidelines](https://github.com/containerd/project/blob/master/CONTRIBUTING.md)
148
149information in our [`containerd/project`](https://github.com/containerd/project) repository.
150
){kind=link}
){kind=link}
){kind=link}