README.md (5262B)
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 8 Go package for creating, managing, inspecting, and destroying cgroups. 9 The 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 16 This 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 22 It uses a single hierarchy and specifies cpu shares as a resource constraint and 23 uses the v1 implementation of cgroups. 24 25 26 ```go 27 shares := uint64(100) 28 control, err := cgroup1.New(cgroup1.StaticPath("/test"), &specs.LinuxResources{ 29 CPU: &specs.LinuxCPU{ 30 Shares: &shares, 31 }, 32 }) 33 defer control.Delete() 34 ``` 35 36 ### Create with systemd slice support 37 38 39 ```go 40 control, err := cgroup1.New(cgroup1.Systemd, cgroup1.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 51 control, err = cgroup1.Load(cgroup1.Default, cgroups.StaticPath("/test")) 52 ``` 53 54 ### Add a process to the cgroup 55 56 ```go 57 if err := control.Add(cgroup1.Process{Pid:1234}); err != nil { 58 } 59 ``` 60 61 ### Update the cgroup 62 63 To update the resources applied in the cgroup 64 65 ```go 66 shares = uint64(200) 67 if 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 78 if err := control.Freeze(); err != nil { 79 } 80 if err := control.Thaw(); err != nil { 81 } 82 ``` 83 84 ### List all processes in the cgroup or recursively 85 86 ```go 87 processes, err := control.Processes(cgroup1.Devices, recursive) 88 ``` 89 90 ### Get Stats on the cgroup 91 92 ```go 93 stats, err := control.Stat() 94 ``` 95 96 By adding `cgroups.IgnoreNotExist` all non-existent files will be ignored, e.g. swap memory stats without swap enabled 97 ```go 98 stats, err := control.Stat(cgroup1.IgnoreNotExist) 99 ``` 100 101 ### Move process across cgroups 102 103 This allows you to take processes from one cgroup and move them to another. 104 105 ```go 106 err := control.MoveTo(destination) 107 ``` 108 109 ### Create subcgroup 110 111 ```go 112 subCgroup, err := control.New("child", resources) 113 ``` 114 115 ### Registering for memory events 116 117 This allows you to get notified by an eventfd for v1 memory cgroups events. 118 119 ```go 120 event := cgroup1.MemoryThresholdEvent(50 * 1024 * 1024, false) 121 efd, err := control.RegisterMemoryEvent(event) 122 ``` 123 124 ```go 125 event := cgroup1.MemoryPressureEvent(cgroup1.MediumPressure, cgroup1.DefaultMode) 126 efd, err := control.RegisterMemoryEvent(event) 127 ``` 128 129 ```go 130 efd, err := control.OOMEventFD() 131 // or by using RegisterMemoryEvent 132 event := cgroup1.OOMEvent() 133 efd, err := control.RegisterMemoryEvent(event) 134 ``` 135 136 ## Examples (v2/unified) 137 138 ### Check that the current system is running cgroups v2 139 140 ```go 141 var cgroupV2 bool 142 if cgroups.Mode() == cgroups.Unified { 143 cgroupV2 = true 144 } 145 ``` 146 147 ### Create a new cgroup 148 149 This creates a new systemd v2 cgroup slice. Systemd slices consider ["-" a special character](https://www.freedesktop.org/software/systemd/man/systemd.slice.html), 150 so 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 155 import ( 156 "github.com/containerd/cgroups/v3/cgroup2" 157 specs "github.com/opencontainers/runtime-spec/specs-go" 158 ) 159 160 res := cgroup2.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 163 m, err := cgroup2.NewSystemd("/", "my-cgroup-abc.slice", -1, &res) 164 if err != nil { 165 return err 166 } 167 ``` 168 169 ### Load an existing cgroup 170 171 ```go 172 m, err := cgroup2.LoadSystemd("/", "my-cgroup-abc.slice") 173 if err != nil { 174 return err 175 } 176 ``` 177 178 ### Delete a cgroup 179 180 ```go 181 m, err := cgroup2.LoadSystemd("/", "my-cgroup-abc.slice") 182 if err != nil { 183 return err 184 } 185 err = m.DeleteSystemd() 186 if err != nil { 187 return err 188 } 189 ``` 190 191 ### Kill all processes in a cgroup 192 193 ```go 194 m, err := cgroup2.LoadSystemd("/", "my-cgroup-abc.slice") 195 if err != nil { 196 return err 197 } 198 err = m.Kill() 199 if err != nil { 200 return err 201 } 202 ``` 203 204 ### Attention 205 206 All static path should not include `/sys/fs/cgroup/` prefix, it should start with your own cgroups name 207 208 ## Project details 209 210 Cgroups is a containerd sub-project, licensed under the [Apache 2.0 license](./LICENSE). 211 As a containerd sub-project, you will find the: 212 213 * [Project governance](https://github.com/containerd/project/blob/main/GOVERNANCE.md), 214 * [Maintainers](https://github.com/containerd/project/blob/main/MAINTAINERS), 215 * and [Contributing guidelines](https://github.com/containerd/project/blob/main/CONTRIBUTING.md) 216 217 information in our [`containerd/project`](https://github.com/containerd/project) repository.