Skip to content

Implement KNE Packet Bridge daemon and CLI subcommand - #762

Open
kraney wants to merge 9 commits into
openconfig:mainfrom
kraney:feat/packet-bridge
Open

Implement KNE Packet Bridge daemon and CLI subcommand#762
kraney wants to merge 9 commits into
openconfig:mainfrom
kraney:feat/packet-bridge

Conversation

@kraney

@kraney kraney commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

1. Overview

This PR introduces the KNE Packet Bridge daemon (bridge.go package) and its CLI subcommand (bridge.go). The packet bridge enables bridging Layer 2 raw Ethernet frames across independent topology segments or linking an external environment (e.g., Borg jobs, developer workstations via veth pairs, or remote KNE clusters) into a KNE cluster over a bidirectional gRPC streaming wire.proto service.

2. Key Components & Architecture

  • Wire Server (bridge.go:264):
    • Implements the wpb.WireServer gRPC service (Transmit bidirectional stream).
    • Opens raw AF_PACKET sockets in promiscuous mode with unix.PACKET_OUTGOING echo suppression to prevent infinite frame reflection loops.
    • Uses bridge.go:150 to coordinate a single raw socket reader per interface across multiple concurrent gRPC subscribers.
    • Implements non-blocking channel dispatch with dropped-frame telemetry (droppedFrames) to isolate slow subscribers and prevent socket reader starvation.
    • Integrates bridge.go:40 buffer pooling for 64KB read buffers to minimize heap allocation and GC churn on the packet capture hot path.
    • Automatically evicts dead or errored interface demuxers from the server cache on teardown.
  • Symmetric Client (client.go:47):
    • Connects to a remote bridge server and forwards Ethernet frames bidirectionally between a local interface and the peer.
    • Features automatic reconnection and configurable retry delays (--retry_interval).
  • CLI Integration (bridge.go:35):
    • Added kne bridge subcommand with server and client modes (plus aliases packet-bridge, packet_bridge).
    • Sets --logtostderr=true by default for seamless container and kubectl logs streaming.
    • Uses signal.NotifyContext for clean termination on SIGINT / SIGTERM.
  • Build & Deployment Artifacts:
    • Dockerfile: Minimal multi-stage Alpine container packaging the kne bridge daemon.
    • Makefile:47-65: Added bridge-docker, kind-load-bridge, and bridge-release targets.
  • Examples & Documentation:
    • paired-bridge.pb.txt: Example topology demonstrating end-to-end Layer 2 ping between two isolated pods via paired bridge server and client nodes.
    • README.md: Architecture diagrams, verification commands (ping, tcpdump), and instructions for bare-host veth bridging.

3. Testing & Verification

  • Unit & Race Tests:
    • Bidirectional packet transmission and buffering tests using in-memory bufconn gRPC connections.
    • Subscriber queue saturation and non-blocking demuxer deadlock verification.
    • Server and client cancellation, retry loops, and config validation tests.
    • All tests pass cleanly under go test -race with zero data races.
  • Compatibility: Verified against the full KNE unit test suite with 0 regressions.

The bridge subcommand sets up a daemon process that will forward
packets into / out of the KNE cluster over a gRPC streaming service.
An external client can use this service to inject or receive packets
to/from a particular interface defined in the topology.
This makes bridge usable in KNE-only situations, to link two separate
clusters (like if one cluster has access another doesn't.) More
importantly, it facilitates easy testing of the feature.
* use a pool for packet buffers
* use cancel so waiting goroutines are freed if readLoop exits on a
  socket error
* use signal.NotifyContext()
* Make sure kne bridge runs root handlers
* distinguish between normal and unexpected stream closure in the client
* Better test coverage
@kraney
kraney force-pushed the feat/packet-bridge branch from b16dcb0 to e6328da Compare September 8, 2026 21:19
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