cgroups — Linux Control Groups
debt(d7/e5/b5/t7)
Closest to 'only careful code review or runtime testing' (d7). detection_hints.tools is empty, and cgroup misconfigurations (e.g., uncapped swap escaping memory.max, v1 vs v2 path confusion, CPU shares vs quota misuse) are not caught by compilers or standard linters. Misconfigurations typically surface only at runtime — often under load or at OOM events — requiring careful review of cgroup hierarchy files or runtime observation via dmesg/systemd tooling. No standard static analysis toolchain covers cgroup configuration correctness.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix is a single inspection command, but actual remediation of common mistakes is non-trivial. Fixing v1-to-v2 path migration, adding memory.swap.max alongside memory.max, or correcting CPU shares/quota confusion in a container runtime or Kubernetes manifest requires touching multiple configuration layers (runtime config, pod specs, systemd units). It's not a one-line swap but also not a full architectural rework.
Closest to 'persistent productivity tax' (b5). cgroups are a foundational resource-management mechanism used by every container runtime and systemd unit on a host. The v1/v2 split, the need to reason about both memory and swap limits, and the CPU shares vs quota distinction impose a persistent cognitive and operational tax on anyone doing containerised workload management. However, most application developers interact with cgroups only indirectly (via Kubernetes limits or systemd MemoryMax), limiting the reach somewhat below b7.
Closest to 'serious trap (contradicts how a similar concept works elsewhere)' (t7). The misconception field explicitly calls out the cgroups-vs-namespaces confusion, and common_mistakes list multiple serious traps: v1 vs v2 path differences, memory.max not capping swap unless memory.swap.max is also set, CPU shares (relative) vs CPU quota (hard cap) behaving very differently. These contradict reasonable mental models — especially for developers coming from other resource-limiting systems. The swap escape is particularly dangerous as it silently bypasses what looks like a hard memory cap.
Also Known As
TL;DR
Explanation
Control groups (cgroups) let the kernel organise processes into hierarchical groups and enforce resource controls per group. Each 'controller' (cpu, memory, io, pids, etc.) tracks and can cap usage for every process in the group. cgroups v1 used one directory tree per controller under /sys/fs/cgroup/<ctrl>/, while cgroups v2 (default on most modern distros) unifies them under a single /sys/fs/cgroup/ tree with a single hierarchy. When you run 'docker run --memory 512m', Docker writes 536870912 to memory.max inside a cgroup it creates for the container. Kubernetes resource requests and limits, systemd service memory caps, and PHP-FPM pool limits via Unit delegation all ultimately configure cgroups. Understanding cgroups is what separates people who can debug 'why is my container being OOM-killed' from people who just add more memory and hope.
Common Misconception
Why It Matters
Common Mistakes
- Confusing cgroups v1 and v2 paths — v1 has /sys/fs/cgroup/memory/, /sys/fs/cgroup/cpu/ etc.; v2 has a single /sys/fs/cgroup/ tree with cgroup.controllers listing active controllers.
- Setting memory.max without considering memory.swap.max — a process can escape a memory cap if swap is uncapped.
- Forgetting that cgroup OOM kills the whole container in most runtime configs — set memory requests above typical spikes to avoid churn.
- Reading /proc/<pid>/cgroup expecting meaningful output inside a container — you see the cgroup path relative to the container's namespace, not the host.
- Confusing CPU shares (relative weight) with CPU quota (hard cap) — shares only matter when CPU is contested; quota caps regardless.
Avoid When
- You control the whole machine and trust every process on it — plain ulimit may suffice.
- Running on a non-Linux OS — macOS and Windows containers use different mechanisms.
When To Use
- You need to cap resource usage per process group — mandatory for multi-tenant hosts.
- Debugging OOM kills or CPU throttling in containerised workloads.
- Building a container runtime or systemd-delegated service manager.