DEV Community: Henry Osei

How Docker Uses cgroups (a /sys/fs/cgroup Walkthrough)

Henry Osei — Sun, 05 Jul 2026 15:15:33 +0000

At some point Docker stops feeling like magic. You run:

docker run --memory=256m --cpus=0.5 nginx

and somehow the container gets exactly 256 MB of memory and half a CPU. Where does that rule actually live? Not in the image, not in the Dockerfile, and not in some private Docker database. It ends up as files under:

/sys/fs/cgroup

That path is one of the places where Docker stops being a product and becomes plain Linux.

`/sys/fs/cgroup` is not a normal folder

List it and it looks like a regular directory:

ls /sys/fs/cgroup

On a modern system using cgroup v2 you'll see entries like:

cgroup.controllers
cgroup.procs
cpu.max
cpu.stat
memory.current
memory.max
pids.current
pids.max
io.stat

None of these sit on disk. /sys/fs/cgroup is a virtual filesystem backed by the kernel: reading a file asks the kernel for cgroup state, and writing one changes how the kernel controls processes.

This is worth pausing on, because it changes how you should picture Docker. Docker isn't watching your container from outside and politely asking it to behave. It writes rules into these files once, and from then on the kernel does the enforcing. Docker is the manager; the kernel is the bouncer.

A container is just a process in a cgroup

A Docker container is not a tiny VM. At runtime it's one or more ordinary Linux processes, and you can prove it yourself:

docker run -d --name web nginx

Ask Docker for the container's main process ID:

docker inspect web --format '{{.State.Pid}}'

Say it returns:

From the host's point of view, that container is a normal Linux process with PID 18432. Now check which cgroup it belongs to:

cat /proc/18432/cgroup

On a cgroup v2 system you'll see something like:

0::/system.slice/docker-<container-id>.scope

That path maps to a directory, usually:

/sys/fs/cgroup/system.slice/docker-<container-id>.scope

and inside it are the control files for this specific container. Everything Docker configured with those --memory and --cpus flags is sitting in there as readable files.

What happens when you set a memory limit

Run a container with a memory limit:

docker run -d \
  --name limited-nginx \
  --memory=256m \
  nginx

Docker does not inject special memory-limiting code into Nginx. The flow is roughly:

docker CLI
  ↓
dockerd
  ↓
containerd
  ↓
runc
  ↓
create process
  ↓
place process into cgroup
  ↓
write memory limit into /sys/fs/cgroup
  ↓
kernel enforces the limit

On cgroup v2 the memory limit lives in memory.max. If the container's cgroup path is:

/sys/fs/cgroup/system.slice/docker-abc123.scope

then Docker writes 268435456 (256 MB in bytes) into:

/sys/fs/cgroup/system.slice/docker-abc123.scope/memory.max

You can look at both the limit and the current usage:

cat /sys/fs/cgroup/system.slice/docker-abc123.scope/memory.max
cat /sys/fs/cgroup/system.slice/docker-abc123.scope/memory.current

Docker wrote memory.max; the kernel keeps memory.current up to date. When the cgroup crosses the limit, the kernel's out-of-memory handling kills a process inside it. If you've ever stared at an OOM-killed container while free -h on the host showed gigabytes of headroom, this is the explanation you were missing: the host had memory, but the cgroup didn't.

What happens when you set a CPU limit

Now run:

docker run -d \
  --name cpu-limited-nginx \
  --cpus=0.5 \
  nginx

On cgroup v2, CPU quota is controlled by cpu.max:

cat /sys/fs/cgroup/system.slice/docker-abc123.scope/cpu.max

which might show:

50000 100000

The first number is the quota and the second is the period, both in microseconds. This cgroup may use 50,000 microseconds of CPU time in every 100,000-microsecond window, which works out to half a CPU. So docker run --cpus=0.5 nginx eventually becomes a scheduler rule of cpu.max = 50000 100000, enforced by the kernel on every scheduling decision. Nobody is pausing Nginx by hand.

What about process limits

This command controls how many processes the container can create:

docker run -d \
  --name pid-limited \
  --pids-limit=100 \
  nginx

On cgroup v2 it maps to pids.max, which would hold 100 here. Two files tell the story:

cat /sys/fs/cgroup/system.slice/docker-abc123.scope/pids.max
cat /sys/fs/cgroup/system.slice/docker-abc123.scope/pids.current

The first is the maximum allowed, the second is how many exist right now. This is your fork-bomb protection. Without a PID limit, a broken or malicious container could keep spawning processes until the host became unstable; with one, the kernel refuses the fork the moment the cgroup hits its cap. Cgroups don't just count things, they say no.

The important file: `cgroup.procs`

Every cgroup needs to know which processes belong to it, and cgroup.procs records exactly that: the PIDs attached to the cgroup. Docker creates a cgroup for the container, then places the container's process into it. Once the process is inside, every rule in that cgroup applies to it and to all of its children:

container process
  └── child process
      └── child process

The whole tree is charged to the same resource-control group. If Nginx forks a dozen workers, they all draw from the same 256 MB, which is exactly what you want from something calling itself a container.

Why the path looks different on different machines

On one system a container shows up under:

/sys/fs/cgroup/system.slice/docker-<container-id>.scope

On another it's:

/sys/fs/cgroup/docker/<container-id>

On Kubernetes you'll see paths involving:

kubepods.slice

The difference comes down to a few variables:

cgroup v1 or cgroup v2
systemd cgroup driver or cgroupfs driver
Docker directly or Kubernetes/containerd
rootful or rootless containers

Don't let the varying paths throw you. Whatever the layout, there's a cgroup directory somewhere, the container's processes are attached to it, and the kernel enforces whatever limits were written there. Find the directory and everything in this post still applies.

Docker does not work alone

"Docker uses cgroups" compresses a whole runtime stack into one sentence. In practice Docker delegates most of the low-level work:

docker CLI
  talks to
dockerd
  talks to
containerd
  talks to
runc
  talks to
Linux kernel

runc deserves special mention. It's the low-level OCI runtime that actually builds the container process out of Linux primitives: it sets up namespaces, configures mounts, applies capabilities, configures seccomp, and places the process into the right cgroups. Docker gives you a pleasant command-line experience on top, but if you want to know where a "container" actually comes into existence, runc is the place to look.

Namespaces isolate what the container sees

Cgroups control what the container can use; namespaces control what it can see. Namespaces answer questions like:

Which processes can this container see?
Which network interfaces can it see?
What hostname does it see?
What filesystem root does it see?

Cgroups answer a different set:

How much memory can this container use?
How much CPU can it consume?
How many processes can it create?
How much I/O can it perform?

Docker needs both. Namespaces create the illusion of a separate machine, and cgroups stop that illusion from eating the whole host. Take away namespaces and the container isn't isolated; take away cgroups and it isn't contained.

A practical inspection flow

To see all of this on your own machine, run:

docker run -d \
  --name cgroup-demo \
  --memory=128m \
  --cpus=0.5 \
  --pids-limit=50 \
  nginx

Get the container PID:

PID=$(docker inspect cgroup-demo --format '{{.State.Pid}}')
echo $PID

Check its cgroup membership:

cat /proc/$PID/cgroup

If it shows:

0::/system.slice/docker-abc123.scope

then the cgroup directory is:

/sys/fs/cgroup/system.slice/docker-abc123.scope

Now inspect the resource files:

cat /sys/fs/cgroup/system.slice/docker-abc123.scope/memory.max
cat /sys/fs/cgroup/system.slice/docker-abc123.scope/memory.current
cat /sys/fs/cgroup/system.slice/docker-abc123.scope/cpu.max
cat /sys/fs/cgroup/system.slice/docker-abc123.scope/pids.max
cat /sys/fs/cgroup/system.slice/docker-abc123.scope/pids.current

That's the actual kernel interface Docker uses to control the container, sitting right there as plain readable files. Once you've cat-ted memory.max yourself, docker run --memory never feels mysterious again.

The mental model

The cleanest way to think about it:

Docker starts Linux processes.

Namespaces make those processes see an isolated world.

Cgroups limit how much of the real machine those processes can consume.

`/sys/fs/cgroup` is the filesystem interface Docker uses to configure those limits.

So when you type:

docker run --memory=512m --cpus=1 nginx

you're really asking Docker to create a process and tell the kernel:

Put this process in its own resource group.
Allow it up to 512 MB of memory.
Allow it up to 1 CPU worth of time.
Track its usage.
Kill or throttle it if it crosses the line.

Containers aren't powerful because Docker invented isolation from scratch. They're powerful because Docker took primitives the kernel already had and packaged them into a workflow developers actually want to use. /sys/fs/cgroup is one of the clearest places to see that with your own eyes, one cat command at a time.

I Thought I Understood Containers. Then I Tried Building One.

Henry Osei — Sat, 04 Jul 2026 21:48:57 +0000

I had just aced my mentor’s Docker exam, so of course I thought I understood containers.

I had said all the right words: namespaces, cgroups, images, layers, PID 1, Kubernetes Pods. Then I typed my first serious command and Linux reminded me that knowing the nouns is not the same thing as building the thing.

$ sudo unshare -p 1 test
unshare: failed to execute 1: No such file or directory

That was the opening scene. I had not even built anything yet. I had typed the flags wrong and accidentally asked unshare to execute a program called 1. This was going to be less “implement Docker” and more “let the kernel correct my confidence, one error at a time.”

v1: namespaces, or the first time PID 1 lied to me

The first version was supposed to be easy: run a process in a new PID namespace and prove it sees itself as PID 1.

So I ran the command the way I thought it worked:

$ sudo unshare --pid bash
# echo $$
25184

That was not PID 1. That was just embarrassing.

The rule I had missed is simple: PID namespaces apply to children. The process that calls unshare --pid does not magically become PID 1. You need to fork. The first child born into the new namespace becomes PID 1.

So the working version was:

$ sudo unshare --pid --fork bash
# echo $$
1

That one line changed the tone. I was inside a different process universe. The shell thought it was process 1. Signals felt different. Orphans came home to it.

Then I ran ps, and got humbled again.

# ps -o pid,ppid,comm
    PID    PPID COMMAND
  25310   25304 bash
  25344   25310 ps

That made no sense at first. I was PID 1, but ps was showing host-looking PIDs. The next reveal: ps does not ask the kernel some pure “what processes exist?” question. It reads files. If /proc still points at the host procfs, your tools will tell you the host story.

So I remounted /proc from inside the namespace:

# mount -t proc proc /proc
# ps -o pid,ppid,comm
    PID    PPID COMMAND
      1       0 bash
      7       1 ps

That was when it clicked. The namespace did not become real to my eyes until /proc agreed with it. Before that, I had isolation, but my tools were reading the old filesystem view.

The UTS namespace lesson was cleaner. I accidentally ran a science experiment.

In one terminal, without a UTS namespace:

$ hostname
ba149abae9bd

Then inside a new UTS namespace:

$ sudo unshare --uts bash
# hostname toybox
# hostname
toybox

Back outside that UTS namespace:

$ hostname
ba149abae9bd

That was my control and treatment. Same machine, same kernel, different hostname view — and the “host” was already a container hostname, which made the containers-inside-containers setup visible in the output. Nothing mystical. Just one isolated kernel data structure doing exactly what the docs said, except now I had seen it with my own hands.

v2: pivot_root, the boss fight

After namespaces, I got overconfident again. The next version was supposed to give the process its own filesystem: a tiny rootfs, a shell, maybe BusyBox. Very container-ish.

My repo had bash scripts for this, not some compiled runtime from a tutorial. So the shape of the attempt was v2.sh, a rootfs, and a command to run inside it.

The parade started with the obvious error:

$ sudo ./v2.sh ./rootfs /bin/sh
exec /bin/sh: no such file or directory

Fine. There was no shell where I said there would be a shell. I fixed that with Alpine’s own BusyBox and hit the more annoying version: the file existed, but the kernel still said it could not run it.

$ ./rootfs/bin/busybox sh
bash: ./rootfs/bin/busybox: cannot execute: required file not found

This is the kind of error that feels personal because you can list the file. You can see the symlink. The computer still refuses.

The plot twist came from file:

$ cd rootfs
$ file bin/busybox
bin/busybox: ELF 64-bit LSB pie executable, ARM aarch64, dynamically linked, interpreter /lib/ld-musl-aarch64.so.1, stripped

The binary was there. The interpreter was not available from the old world. Linux was not saying “your BusyBox file does not exist.” It was saying “from here, I cannot load the interpreter this ELF needs.” Same surface error, different problem.

The fix was not what I first thought. Alpine’s BusyBox did not need to become static. Once Alpine became /, its musl loader would be at /lib/ld-musl-aarch64.so.1, and Alpine’s /bin/sh would be happy. The thing that needed help was the handoff itself: my Ubuntu slim image did not even have pivot_root.

$ pivot_root . put_old
bash: pivot_root: command not found
$ file /bin/busybox
/bin/busybox: ELF 64-bit LSB executable, ARM aarch64, statically linked, stripped
$ /bin/busybox pivot_root . put_old

That was the better plot twist: the old world could not perform the handoff without borrowing a static tool. busybox-static was not my replacement shell inside Alpine. It was the bridge that could run before and during the transition.

Then I hit the Bash hash-cache moment. Alpine was now /, but Bash still remembered a command path from before the filesystem switch. It went hunting for /usr/bin/mount in a world that had just been evicted.

/ # mount -t proc proc /proc
bash: /usr/bin/mount: No such file or directory
/ # hash -r
/ # mount -t proc proc /proc

I had fixed the filesystem and was still debugging an old decision Bash had remembered for me. That is the kind of bug that makes you take a short walk.

Then came the Mac problem. My setup was not “normal Linux laptop, local ext4 disk.” It was Apple Silicon Mac → privileged Ubuntu container → repo mounted from macOS. That means virtiofs was in the story whether I wanted it there or not.

The symptom showed up after the pivot, inside Alpine, which made it stranger. Applet symlinks like mount and ls could fail with Permission denied on the Mac-shared mount, while calling BusyBox directly still worked. The files were there; executing through those symlinks was the weird part.

/ # ls
sh: ls: Permission denied
/ # /bin/busybox ls
bin      dev      etc      lib      proc     put_old
/ # mount -t proc proc /proc
sh: mount: Permission denied
/ # /bin/busybox mount -t proc proc /proc

That is where I stopped trying to make the shared mount behave like a normal Linux filesystem. I moved the rootfs to a container-native path and reran the same idea from there. Boring fix, correct fix.

pivot_root itself still had opinions.

pivot_root: invalid argument

This one was not glamorous either. The new root had to be a mount point. The old root needed somewhere to go. I had to bind-mount the new root onto itself, create oldroot, call pivot_root(newroot, oldroot), chdir("/"), and unmount the old root.

When it finally worked, the reward was tiny and perfect:

/ # cat /etc/os-release
NAME="Alpine Linux"
ID=alpine
VERSION_ID=3.24.1
PRETTY_NAME="Alpine Linux v3.24"

That output felt better than it should have. It was just /etc/os-release, but it meant the process was now living in the filesystem I had assembled. Not Docker magic. Just mounts, an ELF loader problem, a static pivot_root applet, a root pivot, and errors more useful than any clean diagram.

v3: cgroups, or Linux as a filesystem API

The third version was about resource limits. This was where cgroups stopped being “that Kubernetes thing” and became a filesystem API I could write to.

On cgroup v2, everything looked like files:

$ ls /sys/fs/cgroup
cgroup.controllers  cgroup.procs  cgroup.subtree_control  memory.current  memory.max  pids.max

Beautiful, until you write the wrong value to the wrong file at the wrong level.

My first attempt was to create a child cgroup, move the process, and enable controllers casually.

$ sudo mkdir /sys/fs/cgroup/tiny
$ echo +memory | sudo tee /sys/fs/cgroup/cgroup.subtree_control
tee: /sys/fs/cgroup/cgroup.subtree_control: Device or resource busy

That error was the “no internal processes” rule. In cgroup v2, you cannot enable domain controllers on a cgroup that still has normal processes in it. The parent has to become a manager; work happens in children.

So I had to do the evacuation dance: create a child for the shell, move myself into it, then enable controllers on the parent, then create the actual container cgroup.

$ sudo mkdir /sys/fs/cgroup/init
$ echo $$ | sudo tee /sys/fs/cgroup/init/cgroup.procs
18420
$ echo +memory +pids | sudo tee /sys/fs/cgroup/cgroup.subtree_control
+memory +pids
$ sudo mkdir /sys/fs/cgroup/tiny
$ echo 32M | sudo tee /sys/fs/cgroup/tiny/memory.max
32M
$ echo 64 | sudo tee /sys/fs/cgroup/tiny/pids.max
64

After that, the runtime could put the child into /sys/fs/cgroup/tiny/cgroup.procs before executing the workload.

The first OOM test was almost too satisfying. I ran a small memory hog inside the limited cgroup and watched the kernel enforce the number.

$ dmesg | tail -n 3
[ 5221.143892] memory: usage 32768kB, limit 32768kB, failcnt 41
[ 5221.143901] Memory cgroup out of memory: Killed process 18432 (python3) total-vm:89344kB, anon-rss:31812kB, file-rss:0kB, shmem-rss:0kB
[ 5221.143944] oom_reaper: reaped process 18432 (python3), now anon-rss:0kB, file-rss:0kB, shmem-rss:0kB

That line made cgroups real. Not a Docker setting. Not YAML. The kernel enforcing a number I wrote into a file.

Then Kubernetes looked smaller

After this, I deployed to Kubernetes and the concepts no longer felt distant. A Pod was not magic anymore. It was these same pieces with an API in front: namespaces to shape what the process can see, a filesystem root to control what it can touch, and cgroups to limit what it can consume. I would not call my tiny runtime useful, but it made the abstractions stop floating. Docker, containerd, and Kubernetes became less like brands and more like organized versions of the three scripts I had just fought into existence.