[zkwentz]

Summary

This layer decides whether openenvd can isolate, and controls each zone's processes when it can.

• preflight.py. One yes-or-no decision, with the reasons when it's no. Isolation is on when all of these hold:

  • openenvd runs as root;
  • a child process can create user, mount, PID and network namespaces;
  • the cgroup v2 root is writable;
  • an OCI runtime (crun) is installed.

  That's true inside a microVM or a --privileged container. Every failed check says how to fix it, for example (run the container with --privileged).

• cgroups.py. The unit's cgroup v2 tree (control/, zones/<zone>/<container>):

  • limits;
  • cgroup.freeze;
  • atomic cgroup.kill, so a fork bomb can't outrun it;
  • waiting for populated 0;
  • stats.

This replaces an earlier design that probed the host and picked between three tiers. The deployment assumption makes that unnecessary: production runs in a microVM, and everything else simply runs without isolation.

Test plan

• 40 passed and 2 skipped on macOS. The skipped tests need Linux: the real cgroup lifecycle and the namespace check.
• The cgroup tests, including the real-kernel lifecycle, pass in privileged Docker. run.sh in openenvd 5/5: unit assembly, daemon, enforcement check and live tests #1387 runs them on every live run.

Stack

Part of openenvd on kernel primitives (#1053). Review bottom-up; each PR shows only its own layer.

1. openenvd 1/5: manifest contract and unit phases #1383: Contract and phases
2. openenvd 2/5: cgroups and the isolation preflight #1385: cgroups and the isolation preflight ← this PR
3. openenvd 3/5: confinement (seccomp, OCI, shim, forwarders, custody) #1416: Confinement: seccomp, OCI, shim, forwarders, custody
4. openenvd 4/5: relays and the external surfaces #1386: Relays and surfaces
5. openenvd 5/5: unit assembly, daemon, enforcement check and live tests #1387: Unit, daemon, check, live tests

Deployment assumption: openenvd ships in every image. Run privileged (a microVM in production, or docker run --privileged in development) and it isolates. Run any other way and it logs isolation disabled and serves the environment exactly as before.

The trace machinery (hash-chained trace, seal, harness self-report cross-check, /observe) is parked on zkwentz/openenvd-with-trace and is out of this stack's scope.

🤖 Generated with Claude Code

---

Note

Medium Risk
New kernel-facing cgroup and namespace probing code affects process lifecycle and resource limits; misconfiguration could break isolation or teardown, though preflight is designed to disable isolation when prerequisites fail.

Overview
Adds isolation preflight and a cgroup v2 control layer for openenvd: decide whether the unit can run containers, and manage per-zone process trees when it can.

preflight returns a single enable/disable result with log-friendly failure reasons (Linux, root, namespace creation in a forked child, writable cgroup v2 root, OCI runtime discovery for crun/runc/runsc). Failed checks include hints such as --privileged and --cgroupns=private.

cgroups.CgroupTree owns the unit cgroup namespace: adopt_self into control/, create delegated paths like zones/agent/{env,harness}, apply Resources limits (memory, swap off, pids, cpu), move PIDs, freeze/thaw, kill via cgroup.kill or SIGKILL sweep, async wait for frozen/empty, stats, and subtree removal.

Tests cover fake cgroupfs behavior plus an optional root-only Linux lifecycle test.

^{Reviewed by Cursor Bugbot for commit eb77c21. Bugbot is set up for automated code reviews on this repo. Configure here.}