Skip to content

docs(firecracker): document ring-agent installation and the CAP_NET_ADMIN requirement - #205

Merged
Shine-neko merged 1 commit into
mainfrom
docs-firecracker-ring-agent
Jul 25, 2026
Merged

docs(firecracker): document ring-agent installation and the CAP_NET_ADMIN requirement#205
Shine-neko merged 1 commit into
mainfrom
docs-firecracker-ring-agent

Conversation

@Shine-neko

Copy link
Copy Markdown
Contributor

The Firecracker page never mentioned ring-agent or health checks at all, even though the runtime supports command checks — the only place describing how to install the agent was the Cloud Hypervisor page. It also omitted the CAP_NET_ADMIN requirement, 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 the ring binary. Worth stating precisely: Firecracker allocates a TAP for every microVM, not just those publishing ports as Cloud Hypervisor does, so without the capability no Firecracker deployment boots. concepts/runtimes.md claimed 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, and debugfs for those without. The boot-time vsock constraint is restated here, where someone setting up a command check 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-musl produces a static-pie binary with no dynamic dependencies, as the docs claim.
  • The debugfs recipe (write, sif the mode, symlink to enable) applies cleanly to the ubuntu-22.04.ext4 image the e2e suite uses: binary lands at /usr/local/bin/ring-agent with mode 0755, unit and activation symlink both in place.
  • /usr/local/bin and /etc/systemd/system/multi-user.target.wants already exist in that image, so the recipe needs no mkdir.
  • The CAP_NET_ADMIN failure mode was observed directly: a portless deployment fails with could 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-targets clean.

@Shine-neko
Shine-neko merged commit b68838c into main Jul 25, 2026
5 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