Export libcontainer/cgroups from runc

MAINTAINERS

@@ -1,8 +1,8 @@
-This meta-project is maintained by the union of MAINTAINERS for all OCI Projects [1].
-
-Other OCI Projects should list one maintainer per line, with a name, email address, and GitHub username:
-
-Random J Developer <[email protected]> (@RandomJDeveloperExample)
-A. U. Thor <[email protected]> (@AUThorExample)
-
-[1]: https://github.com/opencontainers/
+Akihiro Suda <[email protected]> (@AkihiroSuda)
+Aleksa Sarai <[email protected]> (@cyphar)
+Kir Kolyshkin <[email protected]> (@kolyshkin)
+Mrunal Patel <[email protected]> (@mrunalp)
+Sebastiaan van Stijn <[email protected]> (@thaJeztah)
+Odin Ugedal <[email protected]> (@odinuge)
+Peter Hunt <[email protected]> (@haircommander)
+Davanum Srinivas <davanum@gmail.com> (@dims)

cgroups.go

@@ -0,0 +1,78 @@
+package cgroups
+
+import (
+	"errors"
+)
+
+var (
+	// ErrDevicesUnsupported is an error returned when a cgroup manager
+	// is not configured to set device rules.
+	ErrDevicesUnsupported = errors.New("cgroup manager is not configured to set device rules")
+
+	// ErrRootless is returned by [Manager.Apply] when there is an error
+	// creating cgroup directory, and cgroup.Rootless is set. In general,
+	// this error is to be ignored.
+	ErrRootless = errors.New("cgroup manager can not access cgroup (rootless container)")
+
+	// DevicesSetV1 and DevicesSetV2 are functions to set devices for
+	// cgroup v1 and v2, respectively. Unless
+	// [github.com/opencontainers/cgroups/devices]
+	// package is imported, it is set to nil, so cgroup managers can't
+	// manage devices.
+	DevicesSetV1 func(path string, r *Resources) error
+	DevicesSetV2 func(path string, r *Resources) error
+)
+
+type Manager interface {
+	// Apply creates a cgroup, if not yet created, and adds a process
+	// with the specified pid into that cgroup.  A special value of -1
+	// can be used to merely create a cgroup.
+	Apply(pid int) error
+
+	// GetPids returns the PIDs of all processes inside the cgroup.
+	GetPids() ([]int, error)
+
+	// GetAllPids returns the PIDs of all processes inside the cgroup
+	// any all its sub-cgroups.
+	GetAllPids() ([]int, error)
+
+	// GetStats returns cgroups statistics.
+	GetStats() (*Stats, error)
+
+	// Freeze sets the freezer cgroup to the specified state.
+	Freeze(state FreezerState) error
+
+	// Destroy removes cgroup.
+	Destroy() error
+
+	// Path returns a cgroup path to the specified controller/subsystem.
+	// For cgroupv2, the argument is unused and can be empty.
+	Path(string) string
+
+	// Set sets cgroup resources parameters/limits. If the argument is nil,
+	// the resources specified during Manager creation (or the previous call
+	// to Set) are used.
+	Set(r *Resources) error
+
+	// GetPaths returns cgroup path(s) to save in a state file in order to
+	// restore later.
+	//
+	// For cgroup v1, a key is cgroup subsystem name, and the value is the
+	// path to the cgroup for this subsystem.
+	//
+	// For cgroup v2 unified hierarchy, a key is "", and the value is the
+	// unified path.
+	GetPaths() map[string]string
+
+	// GetCgroups returns the cgroup data as configured.
+	GetCgroups() (*Cgroup, error)
+
+	// GetFreezerState retrieves the current FreezerState of the cgroup.
+	GetFreezerState() (FreezerState, error)
+
+	// Exists returns whether the cgroup path exists or not.
+	Exists() bool
+
+	// OOMKillCount reports OOM kill count for the cgroup.
+	OOMKillCount() (uint64, error)
+}

cgroups_test.go

@@ -0,0 +1,21 @@
+package cgroups
+
+import (
+	"testing"
+)
+
+func TestParseCgroups(t *testing.T) {
+	// We don't need to use /proc/thread-self here because runc always runs
+	// with every thread in the same cgroup. This lets us avoid having to do
+	// runtime.LockOSThread.
+	cgroups, err := ParseCgroupFile("/proc/self/cgroup")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if IsCgroup2UnifiedMode() {
+		return
+	}
+	if _, ok := cgroups["cpu"]; !ok {
+		t.Fail()
+	}
+}

config_blkio_device.go

@@ -0,0 +1,66 @@
+package cgroups
+
+import "fmt"
+
+// BlockIODevice holds major:minor format supported in blkio cgroup.
+type BlockIODevice struct {
+	// Major is the device's major number
+	Major int64 `json:"major"`
+	// Minor is the device's minor number
+	Minor int64 `json:"minor"`
+}
+
+// WeightDevice struct holds a `major:minor weight`|`major:minor leaf_weight` pair
+type WeightDevice struct {
+	BlockIODevice
+	// Weight is the bandwidth rate for the device, range is from 10 to 1000
+	Weight uint16 `json:"weight"`
+	// LeafWeight is the bandwidth rate for the device while competing with the cgroup's child cgroups, range is from 10 to 1000, cfq scheduler only
+	LeafWeight uint16 `json:"leafWeight"`
+}
+
+// NewWeightDevice returns a configured WeightDevice pointer
+func NewWeightDevice(major, minor int64, weight, leafWeight uint16) *WeightDevice {
+	wd := &WeightDevice{}
+	wd.Major = major
+	wd.Minor = minor
+	wd.Weight = weight
+	wd.LeafWeight = leafWeight
+	return wd
+}
+
+// WeightString formats the struct to be writable to the cgroup specific file
+func (wd *WeightDevice) WeightString() string {
+	return fmt.Sprintf("%d:%d %d", wd.Major, wd.Minor, wd.Weight)
+}
+
+// LeafWeightString formats the struct to be writable to the cgroup specific file
+func (wd *WeightDevice) LeafWeightString() string {
+	return fmt.Sprintf("%d:%d %d", wd.Major, wd.Minor, wd.LeafWeight)
+}
+
+// ThrottleDevice struct holds a `major:minor rate_per_second` pair
+type ThrottleDevice struct {
+	BlockIODevice
+	// Rate is the IO rate limit per cgroup per device
+	Rate uint64 `json:"rate"`
+}
+
+// NewThrottleDevice returns a configured ThrottleDevice pointer
+func NewThrottleDevice(major, minor int64, rate uint64) *ThrottleDevice {
+	td := &ThrottleDevice{}
+	td.Major = major
+	td.Minor = minor
+	td.Rate = rate
+	return td
+}
+
+// String formats the struct to be writable to the cgroup specific file
+func (td *ThrottleDevice) String() string {
+	return fmt.Sprintf("%d:%d %d", td.Major, td.Minor, td.Rate)
+}
+
+// StringName formats the struct to be writable to the cgroup specific file
+func (td *ThrottleDevice) StringName(name string) string {
+	return fmt.Sprintf("%d:%d %s=%d", td.Major, td.Minor, name, td.Rate)
+}

config_hugepages.go

@@ -0,0 +1,9 @@
+package cgroups
+
+type HugepageLimit struct {
+	// which type of hugepage to limit.
+	Pagesize string `json:"page_size"`
+
+	// usage limit for hugepage.
+	Limit uint64 `json:"limit"`
+}

config_ifprio_map.go

@@ -0,0 +1,14 @@
+package cgroups
+
+import (
+	"fmt"
+)
+
+type IfPrioMap struct {
+	Interface string `json:"interface"`
+	Priority  int64  `json:"priority"`
+}
+
+func (i *IfPrioMap) CgroupString() string {
+	return fmt.Sprintf("%s %d", i.Interface, i.Priority)
+}

config_linux.go

@@ -0,0 +1,169 @@
+package cgroups
+
+import (
+	systemdDbus "github.com/coreos/go-systemd/v22/dbus"
+	devices "github.com/opencontainers/cgroups/devices/config"
+)
+
+type FreezerState string
+
+const (
+	Undefined FreezerState = ""
+	Frozen    FreezerState = "FROZEN"
+	Thawed    FreezerState = "THAWED"
+)
+
+// Cgroup holds properties of a cgroup on Linux.
+type Cgroup struct {
+	// Name specifies the name of the cgroup
+	Name string `json:"name,omitempty"`
+
+	// Parent specifies the name of parent of cgroup or slice
+	Parent string `json:"parent,omitempty"`
+
+	// Path specifies the path to cgroups that are created and/or joined by the container.
+	// The path is assumed to be relative to the host system cgroup mountpoint.
+	Path string `json:"path"`
+
+	// ScopePrefix describes prefix for the scope name
+	ScopePrefix string `json:"scope_prefix"`
+
+	// Resources contains various cgroups settings to apply
+	*Resources
+
+	// Systemd tells if systemd should be used to manage cgroups.
+	Systemd bool
+
+	// SystemdProps are any additional properties for systemd,
+	// derived from org.systemd.property.xxx annotations.
+	// Ignored unless systemd is used for managing cgroups.
+	SystemdProps []systemdDbus.Property `json:"-"`
+
+	// Rootless tells if rootless cgroups should be used.
+	Rootless bool
+
+	// The host UID that should own the cgroup, or nil to accept
+	// the default ownership.  This should only be set when the
+	// cgroupfs is to be mounted read/write.
+	// Not all cgroup manager implementations support changing
+	// the ownership.
+	OwnerUID *int `json:"owner_uid,omitempty"`
+}
+
+type Resources struct {
+	// Devices is the set of access rules for devices in the container.
+	Devices []*devices.Rule `json:"devices"`
+
+	// Memory limit (in bytes)
+	Memory int64 `json:"memory"`
+
+	// Memory reservation or soft_limit (in bytes)
+	MemoryReservation int64 `json:"memory_reservation"`
+
+	// Total memory usage (memory + swap); set `-1` to enable unlimited swap
+	MemorySwap int64 `json:"memory_swap"`
+
+	// CPU shares (relative weight vs. other containers)
+	CpuShares uint64 `json:"cpu_shares"`
+
+	// CPU hardcap limit (in usecs). Allowed cpu time in a given period.
+	CpuQuota int64 `json:"cpu_quota"`
+
+	// CPU hardcap burst limit (in usecs). Allowed accumulated cpu time additionally for burst in a given period.
+	CpuBurst *uint64 `json:"cpu_burst"` //nolint:revive
+
+	// CPU period to be used for hardcapping (in usecs). 0 to use system default.
+	CpuPeriod uint64 `json:"cpu_period"`
+
+	// How many time CPU will use in realtime scheduling (in usecs).
+	CpuRtRuntime int64 `json:"cpu_rt_quota"`
+
+	// CPU period to be used for realtime scheduling (in usecs).
+	CpuRtPeriod uint64 `json:"cpu_rt_period"`
+
+	// CPU to use
+	CpusetCpus string `json:"cpuset_cpus"`
+
+	// MEM to use
+	CpusetMems string `json:"cpuset_mems"`
+
+	// cgroup SCHED_IDLE
+	CPUIdle *int64 `json:"cpu_idle,omitempty"`
+
+	// Process limit; set <= `0' to disable limit.
+	PidsLimit int64 `json:"pids_limit"`
+
+	// Specifies per cgroup weight, range is from 10 to 1000.
+	BlkioWeight uint16 `json:"blkio_weight"`
+
+	// Specifies tasks' weight in the given cgroup while competing with the cgroup's child cgroups, range is from 10 to 1000, cfq scheduler only
+	BlkioLeafWeight uint16 `json:"blkio_leaf_weight"`
+
+	// Weight per cgroup per device, can override BlkioWeight.
+	BlkioWeightDevice []*WeightDevice `json:"blkio_weight_device"`
+
+	// IO read rate limit per cgroup per device, bytes per second.
+	BlkioThrottleReadBpsDevice []*ThrottleDevice `json:"blkio_throttle_read_bps_device"`
+
+	// IO write rate limit per cgroup per device, bytes per second.
+	BlkioThrottleWriteBpsDevice []*ThrottleDevice `json:"blkio_throttle_write_bps_device"`
+
+	// IO read rate limit per cgroup per device, IO per second.
+	BlkioThrottleReadIOPSDevice []*ThrottleDevice `json:"blkio_throttle_read_iops_device"`
+
+	// IO write rate limit per cgroup per device, IO per second.
+	BlkioThrottleWriteIOPSDevice []*ThrottleDevice `json:"blkio_throttle_write_iops_device"`
+
+	// set the freeze value for the process
+	Freezer FreezerState `json:"freezer"`
+
+	// Hugetlb limit (in bytes)
+	HugetlbLimit []*HugepageLimit `json:"hugetlb_limit"`
+
+	// Whether to disable OOM Killer
+	OomKillDisable bool `json:"oom_kill_disable"`
+
+	// Tuning swappiness behaviour per cgroup
+	MemorySwappiness *uint64 `json:"memory_swappiness"`
+
+	// Set priority of network traffic for container
+	NetPrioIfpriomap []*IfPrioMap `json:"net_prio_ifpriomap"`
+
+	// Set class identifier for container's network packets
+	NetClsClassid uint32 `json:"net_cls_classid_u"`
+
+	// Rdma resource restriction configuration
+	Rdma map[string]LinuxRdma `json:"rdma"`
+
+	// Used on cgroups v2:
+
+	// CpuWeight sets a proportional bandwidth limit.
+	CpuWeight uint64 `json:"cpu_weight"`
+
+	// Unified is cgroupv2-only key-value map.
+	Unified map[string]string `json:"unified"`
+
+	// SkipDevices allows to skip configuring device permissions.
+	// Used by e.g. kubelet while creating a parent cgroup (kubepods)
+	// common for many containers, and by runc update.
+	//
+	// NOTE it is impossible to start a container which has this flag set.
+	SkipDevices bool `json:"-"`
+
+	// SkipFreezeOnSet is a flag for cgroup manager to skip the cgroup
+	// freeze when setting resources. Only applicable to systemd legacy
+	// (i.e. cgroup v1) manager (which uses freeze by default to avoid
+	// spurious permission errors caused by systemd inability to update
+	// device rules in a non-disruptive manner).
+	//
+	// If not set, a few methods (such as looking into cgroup's
+	// devices.list and querying the systemd unit properties) are used
+	// during Set() to figure out whether the freeze is required. Those
+	// methods may be relatively slow, thus this flag.
+	SkipFreezeOnSet bool `json:"-"`
+
+	// MemoryCheckBeforeUpdate is a flag for cgroup v2 managers to check
+	// if the new memory limits (Memory and MemorySwap) being set are lower
+	// than the current memory usage, and reject if so.
+	MemoryCheckBeforeUpdate bool `json:"memory_check_before_update"`
+}

config_rdma.go

@@ -0,0 +1,9 @@
+package cgroups
+
+// LinuxRdma for Linux cgroup 'rdma' resource management (Linux 4.11)
+type LinuxRdma struct {
+	// Maximum number of HCA handles that can be opened. Default is "no limit".
+	HcaHandles *uint32 `json:"hca_handles,omitempty"`
+	// Maximum number of HCA objects that can be created. Default is "no limit".
+	HcaObjects *uint32 `json:"hca_objects,omitempty"`
+}

config_unsupported.go

@@ -0,0 +1,8 @@
+//go:build !linux
+
+package cgroups
+
+// Cgroup holds properties of a cgroup on Linux
+// TODO Windows: This can ultimately be entirely factored out on Windows as
+// cgroups are a Unix-specific construct.
+type Cgroup struct{}