feat(ebpfwindows): add eBPF-for-Windows observability plugin - #2701
Open
Fan Shangxiang (MartinForReal) wants to merge 6 commits into
Open
feat(ebpfwindows): add eBPF-for-Windows observability plugin#2701Fan Shangxiang (MartinForReal) wants to merge 6 commits into
Fan Shangxiang (MartinForReal) wants to merge 6 commits into
Conversation
Fan Shangxiang (MartinForReal)
changed the title
Fan Shangxiang (MartinForReal)
force-pushed
the
proposal/windows-ebpfplugin
branch
from
September 1, 2026 10:11
77b66f7 to
e44a127
Compare
…ility Adds a work-in-progress Windows plugin skeleton that sources network telemetry from the eBPF-for-Windows / WCN (Cilium-on-Windows) data plane, as an alternative to the legacy HNS/VFP hnsstats path. The plugin follows the registry.Plugin contract (self-registering via init), compiles and passes go vet/gofmt, but the live eBPF consumer is not yet implemented -- see the doc proposal for open items. Changes: - pkg/plugin/ebpfwindows: new plugin skeleton - pkg/plugin/include_windows.go: register the plugin - pkg/config/testwith/config-win.yaml: document opt-in enablement - docs: plugin dev guide + readme table entry Signed-off-by: Fan Shangxiang <shafan@microsoft.com>
Iterate on the WIP plugin design and add thorough local tests. - Introduce an EventSource interface and defaultSource placeholder so event production is decoupled and unit-testable without a Windows/eBPF runtime. - Implement a real run loop that reads events, enriches them, and forwards to the external channel (dropping when full and counting lost events). - Guard Start so an injected enricher (tests) is not overwritten by the singleton. - Add unit tests: registration, no-op lifecycle, idempotent Start/Stop, event forwarding + enricher write, nil-event skip, source-error stop, and channel-full drop (all passing; go build / go vet / gofmt clean). The WCN/eBPF-for-Windows reader remains as the defaultSource TODO. Signed-off-by: Fan Shangxiang <shafan@microsoft.com>
Replace the placeholder defaultSource with a real production EventSource: ObserverSource streams flows from the WCN / eBPF-for-Windows observability producer over a gRPC Observer stream on a node-local socket, mirroring the pktmon plugin's proven flow-consumption mechanism. - source.go: ObserverSource (gRPC Observer client, context-cancelled shutdown) - ebpfwindows.go: wire newObserverSource as the default source - source_test.go: in-process gRPC Observer server + local socket to test streaming and start-failure without the WCN runtime - docs: update status (implemented + runtime-validation open item) Environment note: full native eBPF-for-Windows driver provisioning was not possible on this host (not admin, no MSVC/gcc, VM); the consumer is unit- tested via the in-process Observer harness and requires a real Windows Server 2025 + Cilium-on-Windows node for end-to-end validation. Signed-off-by: Fan Shangxiang <shafan@microsoft.com>
Address lint issues surfaced by CI: use grpc.NewClient instead of deprecated grpc.Dial, wrap returned errors (%w), check SetupZapLogger errors, name helper results, use a static sentinel error, and add reasons to nolint directives. No behavior change; all package tests pass and golangci-lint reports zero issues. Signed-off-by: Fan Shangxiang <shafan@microsoft.com>
Normalize each WCN flow before forwarding so Retina advanced flow metrics can consume it: default FORWARDED verdict and a concrete traffic direction, and for DROPPED flows attach a drop_reason extension (mapped from the Cilium drop reason) that the adv_drop metrics label on. Adds normalizeFlow with unit tests and updates the plugin doc. Signed-off-by: Fan Shangxiang <shafan@microsoft.com>
The plugin uses Windows-specific Retina drop-reason enums and is only imported from include_windows.go, but source.go/ebpfwindows.go were unscoped cross-platform files. Rename all package files with the _windows.go suffix (as pktmon does) so the package is Windows-only and CI lint on Linux does not try to type-check the Windows-only normalize logic. Signed-off-by: Fan Shangxiang <shafan@microsoft.com>
Fan Shangxiang (MartinForReal)
force-pushed
the
proposal/windows-ebpfplugin
branch
from
September 1, 2026 10:14
e44a127 to
7ed97c3
Compare
Fan Shangxiang (MartinForReal)
marked this pull request as ready for review
September 1, 2026 10:15
Fan Shangxiang (MartinForReal)
requested a review
from a team
as a code owner
September 1, 2026 10:15
Fan Shangxiang (MartinForReal)
requested review from
Mereta (mereta) and
Isaiah Raya (rayaisaiah)
September 1, 2026 10:15
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
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
1 participant
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.
What does this PR do?
Adds a new Retina plugin,
ebpfwindows, that observes network flows on Windows via theeBPF-for-Windows / WCN (Windows Container Network) observer and surfaces them into Retina flow
metrics with verdict, traffic direction, and drop-reason detail.
Scope
pkg/plugin/ebpfwindows(gated viainclude_windows.go, files renamed*_windows.go/*_windows_test.go).source_windows.go): dials the WCN observer API and streams flow events.normalize_windows.go): maps WCN flow records into Retina*v1alpha1.Flowobjects, populating Verdict, TrafficDirection, and DropReason so they surface in Retina
flow metrics (unit-tested across forward/drop/direction-from-observation-point cases).
Testing
go test ./pkg/plugin/ebpfwindows/... -count=1 -v→ 16/16 pass, includingNormalizeFlow*metric-mapping cases. Validated on a Windows Server 2025 host (Azure VM: build + full test run).
markdownlint, commit-message, CLA, and Windows agent image build (2022) all green.
Why is this needed?
Retina currently lacks a Windows/eBPF-for-Windows flow-observability source. This plugin closes that gap
so Windows node traffic is captured and reported with the same drop/verdict/direction semantics as the
Linux eBPF plugins.
Related GitHub issues