OCI containers and Linux host kernel: repeatable development environment portability across kernel versions

Answer

The OCI runtime specification does not guarantee that a container image will run on any host kernel; it only defines the container lifecycle and configuration. Because containers share the host kernel, any syscall missing in the host will cause the container to receive an ENOSYS error when it tries to invoke that syscall. UID/GID mapping in a user namespace changes the ownership of files created in bind‑mounted directories to the host‑side IDs that correspond to the mapped container IDs. Cgroup v2 limits set on the host are enforced on all processes in the cgroup, regardless of the user namespace view, so a process inside a user namespace sees the same limits but cannot alter them unless it has the necessary privileges.

Confirmed facts

• OCI runtime spec: defines creation, execution, and teardown; does not promise syscall availability.
• Containers use the host kernel; missing syscalls return ENOSYS.
• User namespaces map container UID/GID to different host UID/GID; bind‑mounted files inherit the mapped host IDs.
• cgroup v2 provides a unified hierarchy; limits apply to all tasks in the group, independent of user namespace.
• Processes inside a user namespace observe the same cgroup limits but lack privilege to modify them.

Likely explanation

When a container image is built on a newer kernel that provides a syscall (e.g., a recent clone3 or pidfd_open), running that image on an older host kernel will cause the container to fail at the point the missing syscall is invoked. The failure is not caught by the OCI runtime; it surfaces as an application error. Similarly, if a bind‑mounted source directory is owned by host UID 1000 but the container’s user namespace maps container UID 0 to host UID 200000, files created inside the container will appear as owned by UID 200000 on the host, leading to permission issues for host‑side tools. cgroup v2 limits are hierarchical; setting memory.max on the host cgroup ensures that any process, even one inside a user namespace, cannot exceed that limit, but the container cannot raise the limit without host‑side privileges.

Steps to ensure repeatable portability

1. Verify host kernel provides required syscalls: run the container with strace -e trace=all and look for ENOSYS.
2. If a missing syscall is detected, either rebuild the image on a kernel matching the minimum target or avoid using that syscall (e.g., use older glibc wrappers).
3. Check UID/GID mapping: after running the container, inspect a test file in a bind mount with ls -ln on the host to see the mapped owner.
4. If ownership mismatches cause problems, enable idmapped mounts (requires Linux 5.12+) or use shiftfs where available, or adjust the host directory permissions to accommodate the mapped IDs.
5. Validate cgroup v2 limits: on the host, examine /sys/fs/cgroup/ and cpu.max; inside the container, read /sys/fs/cgroup/memory.max to confirm the same values.
6. If the container needs to adjust limits, ensure it is run with sufficient privileges (e.g., CAP_SYS_ADMIN) or adjust the host cgroup directly.

Missing diagnostic detail

To decide whether to recommend rebuilding the image versus applying idmapped mounts, we need to know the host kernel version and whether idmapped mount support is available. Please provide the output of uname -r and grep -i idmapped /boot/config-$(uname -r) (or confirm if the kernel is ≥5.12).