Skip to content

antctl observe command - #8288

Open
salv-orlando wants to merge 4 commits into
antrea-io:mainfrom
salv-orlando:pr-8191-onto-main
Open

antctl observe command#8288
salv-orlando wants to merge 4 commits into
antrea-io:mainfrom
salv-orlando:pr-8191-onto-main

Conversation

@salv-orlando

Copy link
Copy Markdown
Contributor

Add antctl observe command for live flow streaming from Flow Aggregator

antctl observe is a new command that streams live flow records from a Flow Aggregator's FlowStreamService gRPC endpoint, similar to "kubectl logs -f". It supports filtering (Namespace, Pod, label selector, Service, flow type, IP/CIDR,direction), --since/--max-count/--follow, text/JSON output (with--human-readable byte formatting), automatic Flow Aggregator discovery.
It can be executed from any node with access to K8S API server, provided user has the pods/portforward role. It also supports in-Pod execution from within the Flow Aggregator itself.

New package pkg/antctl/raw/observe/:

  • command.go (cobra command, in-Pod vs. remote connection orchestration)
  • filter.go (CLI-flags-to-request building)
  • connect.go (direct dial or SPDY tunnel through the /portforward subresource, with automatic fallback)
  • discovery.go (cluster-wide or Namespace-scoped Flow Aggregator discovery)
  • auth.go (bearer token/file, client cert, or captured exec/OIDC token; in-Pod mode uses the Pod's own ServiceAccount via rest.InClusterConfig)
  • render.go (text and line-delimited JSON renderers, safe for --follow's unbounded output).

Registered in antctl's command and debug-command lists, now including FlowAggregator mode.
The Client-side gRPC keepalive is tuned just above the FlowStreamService's default 5-minute enforcement policy to avoid disconnections due to GOAWAY.

Notes:

  • authentication with captured OIDC token has currently not been tested.
  • discovery is not available when multiple flow aggregator instances are running: in that case user must explicitly target a F-A instance.

Unit tests
pkg/antctl/raw/observe/{connect,filter,render}_test.go cover request building, dial/tunnel connection-mode selection and fallback, and text/JSON rendering (formatting, truncation, human-readable sizes).

e2e tests

  • new test/e2e/antctlobserve_test.go (TestAntctlObserve) covers:
  • intra/inter-Node and Pod<->external flow capture;
  • every filter type; --since,--max-count, --follow, and their combination (including the server closing the stream at max_count even while following);
  • text vs. JSON output;
  • ServiceAccount bearer-token auth and missing-credential handling;
  • refusing to auto-discover across multiple Flow Aggregator instances plus explicit --flow-aggregator/--flow-aggregator-address targeting;
  • direct vs. auto-with-tunnel-fallback connection modes under NetworkPolicy-enforced denial
  • clean exit on server-side disconnect.

This PR also fixes an antctl ClusterRole gap (missing "get" on deployments) and gives test-e2e-kind.sh's Flow Aggregator instances distinct Helm release names (cluster-scoped RBAC names are release-name-, not Namespace-derived).

Signed-off-by: Dyanngg <dingyang@vmware.com>
Signed-off-by: Dyanngg <dingyang@vmware.com>
Signed-off-by: Dyanngg <dingyang@vmware.com>
@salv-orlando salv-orlando changed the title antclt observe command antctl observe command Aug 18, 2026
"antctl observe" is a new command that streams live flow records from a Flow
Aggregator's FlowStreamService gRPC endpoint, similar to "kubectl logs -f". It
supports filtering (Namespace, Pod, label selector, Service, flow type,
IP/CIDR, direction), --since/--max-count/--follow, text/JSON output (with
--human-readable byte formatting), automatic Flow Aggregator discovery.
It can be executed from any node with access to K8S API server, provided
user has the pods/portforward role. It also supports in-Pod execution
from within the Flow Aggregator itself.

New package pkg/antctl/raw/observe/:
- command.go (cobra command, in-Pod vs. remote connection orchestration)
- filter.go (CLI-flags-to-request building)
- connect.go (direct dial or SPDY tunnel through the /portforward
  subresource, with automatic fallback)
- discovery.go (cluster-wide or Namespace-scoped Flow Aggregator discovery)
- auth.go (bearer token/file, client cert, or captured exec/OIDC token;
  in-Pod mode uses the Pod's own ServiceAccount via rest.InClusterConfig)
- render.go (text and line-delimited JSON renderers, safe for --follow's
  unbounded output).

Registered in antctl's command and debug-command lists, now including
FlowAggregator mode.
The Client-side gRPC keepalive is tuned just above the FlowStreamService's
default 5-minute enforcement policy to avoid disconnections due to GOAWAY.

Notes:
1) authentication with captured OIDC token has currently not been tested.
2) discovery is not available when multiple flow aggregator instances are
   running: in that case user must explicitly target a F-A instance.

Unit tests:
- pkg/antctl/raw/observe/{connect,filter,render}_test.go
  cover request building, dial/tunnel connection-mode selection and fallback,
  and text/JSON rendering (formatting, truncation, human-readable sizes).
- pkg/antctl/raw/observe/{auth,discovery}.go
  cover credential resolution (bearer token/file, client cert, and the
  exec/auth-provider fallback via a captured header), Flow Aggregator
  discovery and lookup by name (via a fake clientset), TLS config construction
  and the ConfigMap CA reader, the direct dialer
- Package unit coverage is estimated to 70.6%.
  Not covered:
  * runE (top-level orchestration)
  * spdyTunnel (needs a real SPDY-upgradeable API server)

e2e tests:
- New test/e2e/antctlobserve_test.go (TestAntctlObserve) covers intra/
  inter-Node and Pod<->external flow capture; every filter type; --since,
  --max-count, --follow, and their combination (including the server closing
  the stream at max_count even while following); text vs. JSON output;
  ServiceAccount bearer-token auth and missing-credential handling; refusing
  to auto-discover across multiple Flow Aggregator instances plus explicit
  --flow-aggregator/--flow-aggregator-address targeting; direct vs. auto-with-
  tunnel-fallback connection modes under NetworkPolicy-enforced denial; and
  clean exit on server-side disconnect. Also fixes an antctl ClusterRole gap
  (missing "get" on deployments) and gives test-e2e-kind.sh's Flow Aggregator
  instances distinct Helm release names (cluster-scoped RBAC names are
  release-name-, not Namespace-derived).
- Exclude "observe" from testAntctlControllerRemoteAccess: unlike every other
  command in that loop, a bare "antctl observe" needs a Flow Aggregator to
  discover and connect to, which fails in jobs that run without
  --flow-visibility.

YAML manifests:
Updated to to include a ClusterRole change for antctl (pods/portforward create,
deployments get, flow-aggregator-ca configmap read) needed for "antctl observe"

AI-Tool-Used: Claude Code
AI-Tool-Use-Level: medium
AI-Code-Category: production
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: Salvatore Orlando <salvatore.orlando@broadcom.com>
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.

2 participants