docs(firecracker): document ring-agent installation and the CAP_NET_ADMIN requirement - #205
Merged
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The Firecracker page never mentioned
ring-agentor health checks at all, even though the runtime supportscommandchecks — the only place describing how to install the agent was the Cloud Hypervisor page. It also omitted theCAP_NET_ADMINrequirement, which is the first thing that stops a Firecracker deployment from booting.CAP_NET_ADMIN. Ring creates the host TAP itself on this runtime (Cloud Hypervisor's VMM does its own), so the capability goes on theringbinary. Worth stating precisely: Firecracker allocates a TAP for every microVM, not just those publishingportsas Cloud Hypervisor does, so without the capability no Firecracker deployment boots.concepts/runtimes.mdclaimed the ports-only version and is corrected too.ring-agent. New "Command health checks" section covering what the agent is, where to get it (each release attaches a static musl build), and how to install it into a disk image — binary plus the systemd unit that actually starts it, which neither page previously showed. Two routes: loop-mount for hosts with root, anddebugfsfor those without. The boot-time vsock constraint is restated here, where someone setting up acommandcheck will actually meet it.The Cloud Hypervisor page now links to that recipe rather than repeating it: the guest side is plain AF_VSOCK on both runtimes, so the same binary and unit apply unchanged. The agent's own doc-comment still described it as the Cloud Hypervisor companion; it now names both runtimes and explains that only the host transport differs.
Also filled in the Firecracker "Known gaps" list, which mentioned only the missing registry pull.
Verified on a host with firecracker and /dev/kvm
Not just proof-read — the instructions were run:
cargo build -p ring-agent --release --target x86_64-unknown-linux-muslproduces astatic-piebinary with no dynamic dependencies, as the docs claim.debugfsrecipe (write,sifthe mode, symlink to enable) applies cleanly to theubuntu-22.04.ext4image the e2e suite uses: binary lands at/usr/local/bin/ring-agentwith mode0755, unit and activation symlink both in place./usr/local/binand/etc/systemd/system/multi-user.target.wantsalready exist in that image, so the recipe needs nomkdir.CAP_NET_ADMINfailure mode was observed directly: a portless deployment fails withcould not create tap '…': operation not permitted, which is what proves the requirement is not ports-only.Docs-only apart from the agent's doc-comment: 779 unit tests pass,
cargo clippy --all-targetsclean.