{"id":1260,"date":"2026-09-30T23:10:45","date_gmt":"2026-09-30T23:10:45","guid":{"rendered":"https:\/\/virtualserversvps.com\/blog\/?p=1260"},"modified":"2026-09-30T23:10:45","modified_gmt":"2026-09-30T23:10:45","slug":"cgroup-v2-io-latency-io-max-disk-qos-vps","status":"publish","type":"post","link":"https:\/\/virtualserversvps.com\/blog\/cgroup-v2-io-latency-io-max-disk-qos-vps\/","title":{"rendered":"Enforcing Disk I\/O QoS with cgroup v2 io.latency and io.max on Noisy Instances"},"content":{"rendered":"

CPU contention has a scheduler with fair shares and quotas. Disk contention historically had almost nothing: a single backup job saturating the block device could push your database’s read latency from 1 ms to 300 ms while every process on the box appeared to be under a cgroup limit. On cgroup v2, two controllers close that gap. io.latency<\/code> guarantees a target latency for a workload; io.max<\/code> imposes hard bandwidth and IOPS ceilings. Together they let you isolate disk access the same way you isolate CPU and memory.<\/p>\n\n

Check That cgroup v2 and the IO Controller Are Live<\/h2>\n\n
# Must print cgroup2fs\nstat -fc %T \/sys\/fs\/cgroup\/\n\n# Confirm the io controller is delegated\ncat \/sys\/fs\/cgroup\/cgroup.controllers\n# expect: cpuset cpu io memory pids ...\n\n# Enable controllers on the root for child use\n echo \"+io\" > \/sys\/fs\/cgroup\/cgroup.subtree_control\n<\/code><\/pre>\n\n
If \/sys\/fs\/cgroup<\/code> reports tmpfs<\/code>, you are still on cgroup v1 and must boot with systemd.unified_cgroup_hierarchy=1<\/code>. Most current distributions default to v2, but minimal VPS images occasionally ship hybrid mode. Verify the controller appears in cgroup.controllers<\/code> before setting any limit – writes to io.max<\/code> on a cgroup whose parent has not delegated the controller fail silently or with an EACCES<\/code>, and the limit never applies.<\/p>\n\n
Identify the Device and Its Major:Minor<\/h2>\n\n
Every IO limit is per-device, addressed by the device’s major and minor number, not by name. On a VPS the root volume is usually a virtio block device (vda<\/code>), but additional volumes may be vdb<\/code>, an NVMe device, or an LVM mapping carrying the dm-<\/code> major. Reading the wrong number is the most common reason a limit appears to have no effect.<\/p>\n\n
lsblk -o NAME,MAJ:MIN,SIZE,TYPE,MOUNTPOINT\n# vda   252:0  80G disk\n# \u2514\u2500vda1 252:1  80G part \/\n\n# Cross-check against the kernel partition table\n cat \/proc\/partitions\n\n# Which device backs a given mount\n df -h \/var\/lib\/mysql\n lsblk -no MAJ:MIN $(findmnt -no SOURCE \/var\/lib\/mysql | xargs basename 2>\/dev\/null) 2>\/dev\/null || true\n<\/code><\/pre>\n\n
Note that limits can be set on either the whole disk (252:0<\/code>) or a partition (252:1<\/code>). Setting a limit on a partition throttles only I\/O issued to that partition; writes to the raw disk bypass it. For a database with its own dedicated volume, applying the limit to the full device is the safer choice because nothing can accidentally escape the cap.<\/p>\n\n
io.max: Hard Ceilings per Device<\/h2>\n\n
io.max<\/code> accepts per-device limits on read\/write bytes per second and IOPS. The four keys are rbps<\/code>, wbps<\/code>, riops<\/code>, and wiops<\/code>; you may set any subset, and max<\/code> clears a limit.<\/p>\n\n
# Create a slice for the backup job\nsystemd-run --slice=backup.slice --unit=nightly-backup --scope true\n\n# Cap the slice: 20 MiB\/s write, 2000 write IOPS on device 252:0\n echo '252:0 wbps=20971520 wiops=2000' > \/sys\/fs\/cgroup\/backup.slice\/io.max\n\n# Read back the effective limits\ncat \/sys\/fs\/cgroup\/backup.slice\/io.max\n# 252:0 rbps=max wbps=20971520 riops=max wiops=2000\n\n# Remove one limit\n echo '252:0 wbps=max' > \/sys\/fs\/cgroup\/backup.slice\/io.max\n<\/code><\/pre>\n\n
Setting io.max<\/code> on a slice applies to every process inside it and to any child cgroups. Because the limit is inherited by children, a runaway worker spawned by the backup job cannot escape the ceiling. This is the correct tool for a bulk job whose only sin is consuming the disk – it needs bytes moved, not the fastest path. Divide the device’s measured throughput, not its theoretical peak, when choosing a number: on a volume that delivers 300 MB\/s sequentially, capping a backup at 20 MB\/s leaves generous headroom for interactive workloads.<\/p>\n\n
io.latency: Guaranteeing the Critical Path<\/h2>\n\n
io.latency<\/code> works the other way round. Instead of capping the offender, you declare an acceptable latency for the workload that must not degrade, and the kernel throttles anything sharing that device until the target is met. It is a target-based controller: it observes the completion latency of each cgroup’s I\/O and applies back-pressure to the cgroups whose target is not the strictest.<\/p>\n\n
# Database slice: keep read latency under 10 ms\n echo '252:0 target=10000' > \/sys\/fs\/cgroup\/db.slice\/io.latency\n\n# The backup slice tolerates more\n echo '252:0 target=100000' > \/sys\/fs\/cgroup\/backup.slice\/io.latency\n\n# Inspect the configured targets\ncat \/sys\/fs\/cgroup\/db.slice\/io.latency\n# 252:0 target=10000\n<\/code><\/pre>\n\n
Values are in microseconds. The lowest target wins priority: the kernel measures observed latency for each cgroup and applies pressure to the others when the target is exceeded. Set a strict target for the database and a generous one for batch work, and the database keeps its 10 ms window even while a backup runs. Note that the strictest target on the device effectively acts as a global latency budget – if you set 10 ms for the database, the controller will throttle the backup regardless of the backup’s own target, which is exactly the isolation you want on a single-volume VPS.<\/p>\n\n
Wiring It Into systemd Services<\/h2>\n\n