Skip to content

feat(firecracker): add native writable mounts - #46

Merged
tianyuzhou95 merged 1 commit into
mainfrom
codex/firecracker-native-writable-mounts
Sep 2, 2026
Merged

feat(firecracker): add native writable mounts#46
tianyuzhou95 merged 1 commit into
mainfrom
codex/firecracker-native-writable-mounts

Conversation

@tianyuzhou95

Copy link
Copy Markdown
Collaborator

Summary

  • add Firecracker extra_config.nativeWritableMounts for guest directories
    backed directly by the sandbox's private ext4 writable image
  • bind each private ext4 directory into the assembled guest root without
    adding another Firecracker drive or changing the writable-layer quota
  • preserve the existing checkpoint format because native directory data is
    already part of overlay.ext4 and mount state is part of the VM snapshot
  • validate target paths and overlaps, expose raw runtime configuration in the
    administrative sbox start command, and document the storage contract

Example:

{
  "nativeWritableMounts": [
    {"target": "/var/lib/docker"}
  ]
}

This gives nested storage users a native ext4 path while the guest root
remains EROFS plus OverlayFS. The root upper/work directories and native
writable directories share the same storage_mb capacity and lifecycle.

Validation

  • make check-fmt
  • make vet
  • make test
  • full Firecracker E2E on a KVM node, including crash recovery, ten
    consecutive checkpoints, restore, checkpoint-after-restore, quota, network,
    and Redis traffic
  • Docker 27 dind guest: dockerd automatically selected overlay2, pulled
    BusyBox, and ran a nested container with no explicit storage-driver setting
  • Docker 29 dind guest: the default containerd image store automatically
    selected the equivalent overlayfs snapshotter on the native ext4 path

Allow Firecracker start requests to select guest directories that are
backed directly by the sandbox's private ext4 writable image. This lets
nested storage users such as dockerd avoid placing their overlay on the
root OverlayFS while keeping a single storage quota and lifecycle.

Forward runtime extra config to handlers, validate mount targets, and
teach firecracker-agent to bind per-target native directories into the
guest. Document checkpoint semantics and cover configuration, protocol,
mount safety, recovery, and end-to-end persistence.

Signed-off-by: Tianyu Zhou <albert.zty@antgroup.com>
@tianyuzhou95
tianyuzhou95 merged commit 5970730 into main Sep 2, 2026
24 of 26 checks passed
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