Resource Isolation

Cgroups Integration 💎

Super integrates directly with the Linux Kernel’s Control Groups (v2) to provide hardware-level isolation for managed processes.

Context: For the “noisy neighbor” production scenario, see Resource Isolation (scenario).

Configuration Reference

Resource limits are defined per program in super.toml.

[[programs]]
name = "data-processor"
command = "./worker"

[programs.resource_limits]
# Memory Limit (Bytes)
# If the process (and its children) exceed this, the OOM Killer terminates it.
memory_limit = 1073741824  # 1 GB

# CPU Quota (Percentage)
# 100.0 = 1 full core. 50.0 = half a core.
# The scheduler throttles the process if it exceeds this usage.
cpu_quota = 200.0  # 2 Cores

Requirements

• OS: Linux only.
• Kernel: Cgroups v2 enabled (Standard on Ubuntu 22.04+, Debian 11+, Fedora).
• Privileges: The superd daemon usually requires root privileges to create and manage cgroups (writing to /sys/fs/cgroup).

Monitoring Limits

You can check if Cgroups are being enforced via the metrics endpoint:

curl http://localhost:9002/metrics | grep cgroup
# super_cgroup_enforced_total 5

Superd logs include Applying limits on start and Hot-updating resources when limits change on a running process.

Verify & adjust

Pre-flight

• Run superd-premium on Linux with permission to write under /sys/fs/cgroup (typically root on bare metal).
• Containers: cgroup mounts are often read-only unless you provide a writable cgroup namespace or run privileged. Limits will not apply if Super logs a read-only cgroup warning at startup.
• Confirm cgroup v2: mount | grep cgroup2 (or stat -fc %T /sys/fs/cgroup/ shows cgroup2fs).

Confirm a program is in a cgroup

Each managed program gets a directory named by its UUID:

# Replace <id> with the program UUID from `super list` or the API
ls /sys/fs/cgroup/super/<id>/
cat /sys/fs/cgroup/super/<id>/cpu.max      # e.g. 50000 100000 ≈ 50% of one core
cat /sys/fs/cgroup/super/<id>/memory.max   # hard memory cap in bytes

When the process stops, Super removes the cgroup directory (after_stop cleanup).

Hot-update limits (no restart for CPU quota)

Change limits on a running program without restarting it (CPU quota is updated in place):

# CLI (Premium)
super update data-processor --cpu 10
super update data-processor --memory 536870912

# API
curl -X PUT http://127.0.0.1:9002/api/programs/<id> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"resource_limits": {"cpu_quota": 10.0, "memory_limit": 536870912}}'

Re-check cpu.max / memory.max under /sys/fs/cgroup/super/<id>/ and watch process CPU with top -p <pid>.

Troubleshooting