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 (v1)
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.LinuxCPU{
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## Examples (v2/unified)
137
138### Check that the current system is running cgroups v2
139
140```go
141var cgroupV2 bool
142if cgroups.Mode() == cgroups.Unified {
143 cgroupV2 = true
144}
145```
146
147### Create a new cgroup
148
149This creates a new systemd v2 cgroup slice. Systemd slices consider ["-" a special character](https://www.freedesktop.org/software/systemd/man/systemd.slice.html),
150so the resulting slice would be located here on disk:
151
152* /sys/fs/cgroup/my.slice/my-cgroup.slice/my-cgroup-abc.slice
153
154```go
155import (
156 cgroupsv2 "github.com/containerd/cgroups/v2"
157 specs "github.com/opencontainers/runtime-spec/specs-go"
158)
159
160res := cgroupsv2.Resources{}
161// dummy PID of -1 is used for creating a "general slice" to be used as a parent cgroup.
162// see https://github.com/containerd/cgroups/blob/1df78138f1e1e6ee593db155c6b369466f577651/v2/manager.go#L732-L735
163m, err := cgroupsv2.NewSystemd("/", "my-cgroup-abc.slice", -1, &res)
164if err != nil {
165 return err
166}
167```
168
169### Load an existing cgroup
170
171```go
172m, err := cgroupsv2.LoadSystemd("/", "my-cgroup-abc.slice")
173if err != nil {
174 return err
175}
176```
177
178### Delete a cgroup
179
180```go
181m, err := cgroupsv2.LoadSystemd("/", "my-cgroup-abc.slice")
182if err != nil {
183 return err
184}
185err = m.DeleteSystemd()
186if err != nil {
187 return err
188}
189```
190
191### Attention
192
193All static path should not include `/sys/fs/cgroup/` prefix, it should start with your own cgroups name
194
195## Project details
196
197Cgroups is a containerd sub-project, licensed under the [Apache 2.0 license](./LICENSE).
198As a containerd sub-project, you will find the:
199
200 * [Project governance](https://github.com/containerd/project/blob/main/GOVERNANCE.md),
201 * [Maintainers](https://github.com/containerd/project/blob/main/MAINTAINERS),
202 * and [Contributing guidelines](https://github.com/containerd/project/blob/main/CONTRIBUTING.md)
203
204information in our [`containerd/project`](https://github.com/containerd/project) repository.
View as plain text