Skip to content

feat(standalone): support runc-only nodes with external filestore - #77

Open
rcyw wants to merge 1 commit into
inclusionAI:mainfrom
rcyw:feat/standalone-external-filestore
Open

rcyw wants to merge 1 commit into
inclusionAI:mainfrom
rcyw:feat/standalone-external-filestore

Conversation

@rcyw

@rcyw rcyw commented Sep 21, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • make the gVisor payload optional for standalone images that only need the native runc runtime
  • add a dedicated external-filestore mode that uses a real host filesystem instead of a loop-backed ext4.img
  • validate image/runtime capabilities before launch and exercise runc plus opt-in KVM device injection in CI

Motivation

Standalone deployments currently always package and configure runsc, and a configured filestore_dir_size creates a loop-backed filesystem below the standalone data directory. Bare-metal runc environments should be able to omit the unused gVisor payload and place sandbox writable data on a dedicated filesystem without silently falling back to the parent disk after a mount or restart failure.

Design

Runtime capabilities

AKERNEL_ENABLE_RUNSC=false now skips the gVisor payload at build time. Disabling runsc requires AKERNEL_ENABLE_RUNC=true, and the standalone launcher removes the runsc runtime entry while enabling runc.

The image records both runsc and runc capabilities in OCI labels. The launcher checks the requested runtime configuration against those labels before creating the node container, preventing a runc-only image from starting with a stale runsc configuration. Images predating the runsc label retain the historical assumption that runsc is present.

When runc is enabled, the launcher verifies the host overlay, EROFS, and loop capabilities and loads only missing modules.

External filestore

STANDALONE_FILESTORE_DIR selects an existing host mountpoint. Before launch, the launcher verifies that the path:

  • resolves to a writable mountpoint
  • is not loop-backed
  • has a filesystem UUID when backed by a block device
  • is neither / nor overlapping the standalone data directory
  • contains no legacy ext4.img

The generated sandboxd configuration sets filestore_dir_size="", so sandboxd uses the real filesystem directly. The launcher records the expected source, filesystem type, and UUID under the persistent standalone data directory and mounts that state read-only at /etc/akernel/external-filestore.

External-filestore mode also sets AKERNEL_EXTERNAL_FILESTORE_REQUIRED=true. Validation runs both at the standalone container entrypoint and in sandboxd's ExecStartPre, so missing state, a changed filesystem identity, a loop device, a legacy image, or a non-writable mount fails closed across container and service restarts.

This does not bind the YuanRong service lifecycle to sandboxd. Cross-component readiness remains separate from the storage guard.

Compatibility

The default image still includes runsc, runc remains opt-in, and standalone deployments that do not set STANDALONE_FILESTORE_DIR retain the existing loop-backed filestore behavior.

Validation

  • make SHELL=/bin/bash deploy-script-check
  • make SHELL=/bin/bash check
  • built and started a runc-only standalone image with a dedicated ext4 filestore
  • verified normal runc sandbox command execution and file I/O
  • verified /dev/kvm is absent by default and injected only for runc sandboxes requesting extra_config={"enableKVM": true}
  • verified sandbox cleanup leaves no runc shim, filestore loop device, or ext4.img
  • verified normal sandboxd restart and full container restart
  • verified a changed filesystem UUID prevents sandboxd from starting and that restoring the identity permits explicit recovery
  • verified / and a mount containing the standalone data directory are rejected before the write probe

Allow standalone nodes to omit the gVisor payload when runc is the only required runtime, and prepare only the missing host filesystem capabilities before starting the node.

Support a dedicated external filestore without creating a loop-backed image. Persist its filesystem identity and validate it both at container entry and before every sandboxd service start so a missing host mount fails closed across either restart path.

Cover the launcher and restart guard with shell tests, and build and exercise a real runc-only standalone sandbox in CI.

Signed-off-by: wayne <rcywjo@gmail.com>
@rcyw
rcyw marked this pull request as ready for review September 21, 2026 16:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant