Repository navigation
feat(wireguard): add automatic userspace fallback - #199
Conversation
- Fall back to wireguard-go when kernel WireGuard is unsupported - Manage userspace process recovery and cleanup through the existing Engine - Bundle wireguard-go in the agent image - Fix VXLAN device reuse during repeated reconciliation - Add lifecycle and compatibility tests and document validation results
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #199 +/- ##
===========================================
+ Coverage 28.36% 46.42% +18.06%
===========================================
Files 35 39 +4
Lines 3624 4213 +589
===========================================
+ Hits 1028 1956 +928
+ Misses 2431 2040 -391
- Partials 165 217 +52
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
@Jonny-ee Please fix linter, thanks |
- Handle cleanup errors, tidy dependencies, and fix Markdown lint - Isolate route and ipset operations for failure injection - Add reconciliation, lifecycle, peer update, and readiness tests
|
@njucjc Could you please take another look? Thanks! |
It's a very big PR, could you add a e2e test report? |
There was a problem hiding this comment.
🟡 Changes recommended
Userspace close failures can permanently block recovery, and the implementation does not satisfy the linked issue’s central requirements.
2 open findings
What changed in this PR
Adds kernel-first WireGuard userspace fallback with managed recovery and cleanup.
Changes:
- Bundles and manages
wireguard-go. - Integrates recovery with Engine reconciliation.
- Improves VXLAN reuse and adds extensive tests.
| File | Description |
|---|---|
Dockerfile |
Builds and bundles wireguard-go. |
go.mod |
Reclassifies the errors dependency. |
docs/20260918-support-wireguard-userspace.md |
Documents fallback design and validation. |
hack/wireguard-fallback-cloud-init.yaml |
Creates a fallback test environment. |
pkg/networkengine/vpndriver/driver.go |
Adds optional lifecycle injection. |
pkg/networkengine/vpndriver/wireguard/wireguard.go |
Integrates userspace lifecycle and reconciliation. |
pkg/networkengine/vpndriver/wireguard/device_linux.go |
Manages backend selection and UAPI access. |
pkg/networkengine/vpndriver/wireguard/device_linux_test.go |
Tests device management. |
pkg/networkengine/vpndriver/wireguard/process_linux.go |
Manages the userspace subprocess. |
pkg/networkengine/vpndriver/wireguard/process_linux_test.go |
Tests subprocess behavior. |
pkg/networkengine/vpndriver/wireguard/recovery_linux.go |
Implements recovery and backoff. |
pkg/networkengine/vpndriver/wireguard/recovery_linux_test.go |
Tests recovery policy. |
pkg/networkengine/vpndriver/wireguard/reconcile_linux_test.go |
Tests reconciliation and cleanup. |
pkg/networkengine/vpndriver/wireguard/regression_linux_test.go |
Covers peer and cleanup regressions. |
pkg/networkengine/vpndriver/wireguard/regression_integration_linux_test.go |
Adds privileged regression tests. |
pkg/networkengine/vpndriver/wireguard/integration_linux_test.go |
Tests fallback networking end-to-end. |
pkg/networkengine/routedriver/vxlan/utils.go |
Reuses unchanged VXLAN links. |
pkg/networkengine/routedriver/vxlan/utils_test.go |
Verifies VXLAN reuse. |
pkg/engine/engine.go |
Serializes runtime recovery and shutdown. |
pkg/engine/tunnel.go |
Integrates lifecycle, health, and cleanup. |
pkg/engine/runtime.go |
Schedules driver reconciliation. |
pkg/engine/recovery_test.go |
Tests Engine recovery behavior. |
pkg/engine/compatibility_test.go |
Tests compatibility with existing drivers. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| case <-done: | ||
| c.mu.Lock() | ||
| defer c.mu.Unlock() | ||
| return c.closeErr |
| | [VXLAN helper](../pkg/networkengine/routedriver/vxlan/utils.go) | Return the existing VXLAN device when its configuration is unchanged. Repeated `LinkAdd` calls previously returned `file exists`, blocking full network recovery after a userspace failure. Only this branch is fixed, with a stronger regression test. | | ||
| | Related Go tests and [automatic-fallback environment configuration](../hack/wireguard-fallback-cloud-init.yaml) | Verify backend selection, lifecycle management, shared Engine compatibility, and recovery with real networking. Forced backend selection remains a test-only facility. | | ||
|
|
||
| This change does not redesign Raven's dataplane or remove dependencies on VXLAN, TUN, routing, or netfilter. It adds no public backend-selection flag, Gateway field, Node label, CRD, or WireGuard metric. It does not modify Libreswan or the shared ipset implementation, extend VXLAN functionality, or address unrelated historical issues. |
There was a problem hiding this comment.
Thanks for pointing this out. I agree that the current PR does not implement per-Gateway vpnDriver selection or a reduced-kernel dataplane that removes VXLAN, iptables, and ipset dependencies.
Those were not intended requirements for this change. The intended scope is transparent kernel-to-userspace WireGuard fallback: users select the WireGuard driver, and Raven automatically uses wireguard-go only when the kernel backend is unsupported.
The wording of issue #193 was too broad and conflated these two goals. I will update the issue and PR description to clarify the scope. Reduced-kernel dataplane support, if still needed, should be tracked separately.
E2E Test ReportDate: 2026-10-11 Commit: Scope and evidenceThis report covers the repository's WireGuard network-namespace integration Test environmentAll Go tests and integration suites in this report run directly as root in
The userspace binary used by the integration runs has SHA-256 Docker is used only for the release image build and artifact extraction. Release image build command (run on the host from the repository root): docker build --platform linux/arm64 \
--build-arg TARGETOS=linux --build-arg TARGETARCH=arm64 \
--build-arg GITCOMMIT=76519ec3608f92ca9613d8c29e42c5edc9117afd \
-t raven-agent:e2e-report .VM preparation and executionThe test VM provides Go, sudo mkdir -p /var/run/wireguard
sudo sysctl -w net.ipv4.ip_forward=1 \
net.ipv4.conf.all.rp_filter=0 net.ipv4.conf.default.rp_filter=0
sudo ipset create ravencheck hash:net,net
sudo ipset destroy ravencheckThe directory is the mount point used by isolated per-node UAPI namespaces. The suites ran sequentially because they reuse namespace and device names. On cd /workspace
sudo -E env PATH="$PATH" RAVEN_WG_DEVICE_INTEGRATION=1 \
go test ./pkg/networkengine/vpndriver/wireguard \
-run '^TestWireGuardDeviceIntegration$' -count=1 -v -timeout=15m
sudo -E env PATH="$PATH" RAVEN_WG_REGRESSION_INTEGRATION=1 \
go test ./pkg/networkengine/vpndriver/wireguard \
-run '^TestWireGuardRegressionIntegration$' -count=1 -v -timeout=15m
sudo -E env PATH="$PATH" RAVEN_WG_INTEGRATION=1 \
go test ./pkg/networkengine/vpndriver/wireguard \
-run '^TestWireGuardNetworkIntegration$' -count=1 -v -timeout=15mFor automatic fallback, cd /workspace
sudo -E env PATH="$PATH" RAVEN_WG_AUTO_FALLBACK_INTEGRATION=device \
go test ./pkg/networkengine/vpndriver/wireguard \
-run '^TestWireGuardAutomaticFallbackIntegration$' -count=1 -v -timeout=15m
sudo -E env PATH="$PATH" RAVEN_WG_AUTO_FALLBACK_INTEGRATION=network \
go test ./pkg/networkengine/vpndriver/wireguard \
-run '^TestWireGuardAutomaticFallbackIntegration$' -count=1 -v -timeout=15mThe fallback test itself calls real netlink Results
All listed integration suites explicitly enable their opt-in environment Recorded output excerptsThe following lines are extracted from the local run output. Durations in Coverage-to-test mappingEach behavior below maps to a passing test or subtest. Durations and results
The integration test source is integration_linux_test.go and the regression source is regression_integration_linux_test.go. The general repository and race commands do not enable the opt-in integration tests; those are covered by the explicit rows above. Known limitations, untested areas and risks
These boundaries leave residual risk for unsupported architectures, kernel and Additional scenarios not covered by this E2E run
Conclusion and release recommendationAll listed WireGuard integration, fallback, regression, repository, race and This report should not be used as a compatibility sign-off for amd64, other |
done |
Description
Fixes #193
Enable Raven to establish WireGuard tunnels on nodes without kernel WireGuard support by automatically falling back to
wireguard-go.The existing
wireguarddriver remains kernel-first. Fallback occurs only when kernel device creation returnsEOPNOTSUPP/ENOTSUP. No new public configuration or CRD changes are required.Changes Made
wireguard-goversion in the agent image.See the design document for implementation details, compatibility considerations, and completed validation.