How to Implement Linux Control Groups (cgroups) CPU CFS Quota for Strict Throttling

When running multiple applications on a single Linux server, systems administrators traditionally rely on process priorities (niceness) to manage CPU resources. However, nice values are merely suggestions to the kernel scheduler. If a low-priority background data processing script suddenly spawns 50 threads and enters a tight infinite loop, it can still consume 100% of the CPU, starving mission-critical web server processes and causing system instability.

To achieve absolute, mathematically guaranteed resource isolation, administrators must use Control Groups (cgroups). Specifically, to enforce a hard ceiling on CPU consumption, you must utilize the Completely Fair Scheduler (CFS) Bandwidth Control subsystem via the cpu.cfs_quota_us parameter.

This guide explains the architecture of the CFS bandwidth controller and how to manually configure cgroups to strictly throttle a runaway application.

Understanding CFS Bandwidth Architecture

The Linux kernel’s CFS scheduler allocates CPU time in discrete periods, typically measured in microseconds (us). The bandwidth controller operates on two fundamental variables:

1. cpu.cfs_period_us: The length of the accounting period (the time window). The default is usually 100,000 microseconds (100 milliseconds).
2. cpu.cfs_quota_us: The absolute maximum amount of CPU time the processes in this cgroup are allowed to execute during that specific period.

The Math of Quotas:

• If period = 100,000 and quota = 50,000, the cgroup gets exactly 50% of a single CPU core. Once the application runs for 50ms, the kernel forcibly pauses it. It cannot execute a single instruction until the remaining 50ms of the period expires.
• If period = 100,000 and quota = 200,000, the cgroup is allowed to consume exactly 200% CPU (meaning it can fully saturate two physical CPU cores simultaneously).
• If quota = -1 (the default), there is no limit.

Step 1: Creating the Control Group

We will create a cgroup manually by interacting directly with the sysfs virtual filesystem. (Note: Modern systems use systemd for cgroup management, but manual creation is essential for understanding the underlying mechanics).

Navigate to the CPU cgroup controller directory:

cd /sys/fs/cgroup/cpu

(If you are on a cgroups v2 unified hierarchy system, the path is /sys/fs/cgroup, and the files are named slightly differently, e.g., cpu.max).

Create a new directory. The kernel automatically populates this directory with the necessary cgroup parameter files:

sudo mkdir my_throttled_app
cd my_throttled_app
ls

You will see files like cgroup.procs, cpu.cfs_period_us, and cpu.cfs_quota_us.

Step 2: Configuring the Strict CPU Quota

Let’s enforce a strict limit. We want to restrict any application running in this cgroup to a maximum of 25% of a single CPU core.

Check the default period (it should be 100000):

cat cpu.cfs_period_us

Calculate the quota: 25% of 100,000 is 25,000.

Write this value into the quota file:

echo 25000 | sudo tee cpu.cfs_quota_us

The hard ceiling is now established. The kernel will unconditionally pause execution if the processes exceed this time slice.

Step 3: Attaching a Process to the Cgroup

To demonstrate the throttling, let’s create an artificial runaway process. Open a new terminal window and run a CPU stress command (or a simple infinite shell loop) and record its Process ID (PID):

# Generate an infinite loop to consume 100% of a core
bash -c "while true; do true; done" &
echo $!

Assume the output PID is 54321.

If you run top -p 54321, you will see the bash process consuming 99.9% CPU.

Now, attach this process to our throttled cgroup by writing its PID into the cgroup.procs file:

echo 54321 | sudo tee /sys/fs/cgroup/cpu/my_throttled_app/cgroup.procs

Step 4: Observing the Throttling

Switch back to your top window. Instantly, the CPU consumption of the bash process will plummet from 99.9% to exactly 25.0%.

You can view the kernel’s internal statistics to see the throttling in action:

cat /sys/fs/cgroup/cpu/my_throttled_app/cpu.stat

You will see three critical metrics:

• nr_periods: The total number of 100ms periods that have elapsed.
• nr_throttled: The number of times the kernel had to forcibly pause the process because it hit the quota.
• throttled_time: The total time (in nanoseconds) the process spent paused, waiting for the next period to begin.

Step 5: Teardown

To remove the cgroup restriction, you must first kill all processes running inside it (or move them to the root cgroup). Once the cgroup.procs file is empty, you can delete the directory.

kill 54321
sudo rmdir /sys/fs/cgroup/cpu/my_throttled_app

Conclusion

Relying on process niceness for server stability is a fundamentally flawed strategy in multi-tenant environments. By leveraging the absolute mathematical precision of the Linux CFS Bandwidth Controller and cpu.cfs_quota_us, systems administrators can construct impenetrable resource boundaries, ensuring that runaway microservices or misconfigured scripts can never impact the performance of critical infrastructure workloads.