Skip to content

bug(docs): workload image requirements are out of date after #2942, #3386, #3214 #3965

Description

@zanetworker

User Story

As a user building a custom sandbox image, I want the documented image requirements to match what OpenShell actually needs, so that I don't add packages or configuration the runtime no longer uses.

Problem Statement

Since the RFC 0012 sandbox architecture (#2942), plus #3386 and #3214, the workload image requirements in the docs no longer match the code:

Doc Says Code on main (5acaaba19)
examples/bring-your-own-container/README.md:79 and Dockerfile:11-14 Install iproute2 for network namespace isolation; nftables enables bypass detection #2942 removed crates/openshell-supervisor-process/src/netns/. No crate outside tests runs ip, nft, nsenter, or dmesg. The workload runs with networking off (crates/openshell-driver-podman/README.md: "No nftables or nested network namespace setup runs in the sandbox"), and raw or kernel sockets are blocked by seccomp (crates/openshell-sandbox/src/sandbox/linux/seccomp.rs)
examples/bring-your-own-container/README.md:72-75, docs/how-it-works/sandboxes/runtimes.mdx:291 Docker and Podman images without USER must set run_as_user/run_as_group in policy Both drivers fall back to UID/GID 1000 (crates/openshell-driver-docker/src/lib.rs:650, crates/openshell-driver-podman/src/container.rs:628, from #3386)
docs/how-it-works/sandboxes/runtimes.mdx:85 "Docker is also required to build sandbox images from local directories or Dockerfiles" The CLI no longer builds images (#3214)
examples/bring-your-own-container/README.md:76-77 Create /sandbox "until OCI working-directory support is added" Docker now uses the image WORKDIR (runtimes.mdx:295); Podman, Kubernetes, and VM use /sandbox

Related: #3280 and #2382 describe the supervisor running ip/nft/dmesg from the workload image. That code was removed in #2942, so both issues may now be obsolete.

Impact / Why This Matters

The BYOC example is the reference for building custom sandbox images. Users following it:

  • add iproute2 and nftables to every image for no benefit;
  • believe USER-less base images need policy changes;
  • expect Dockerfile builds that the CLI no longer does.

Downstream distributions that copy these requirements into their own docs spread the same errors. The workaround is reading the driver and sandbox source, which most image authors won't do.

Acceptance Criteria

Reproduction Steps

  1. Read examples/bring-your-own-container/README.md ("Running your own app") and docs/how-it-works/sandboxes/runtimes.mdx ("Sandbox User Identity").
  2. Compare with the code references in the table above.

Verified by code inspection on main at 5acaaba19 and in release v0.1.2. I have not run an end-to-end test with an image that lacks iproute2, nftables, and USER. It would be worth confirming on each in-tree driver, and checking that no extension driver still needs these tools.

Environment

  • OpenShell: main at 5acaaba19, v0.1.2
  • Runtime: Docker, Podman, Kubernetes, VM (docs issue, driver-independent)

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    state:triage-neededOpened without agent diagnostics and needs triage

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions