/doca-flow-grpc-server

license: Apache-2.0
name: doca-flow-grpc-server
description: >
  PLAINTEXT-ONLY: the shipped `doca_flow_grpc` server uses
  `grpc::InsecureServerCredentials()` with NO TLS / mTLS / token-auth
  knob on the binary — transport security must come from external
  infrastructure (e.g. an mTLS proxy / sidecar) on a trusted segment.
  Use this skill when bringing up, configuring, hardening, or
  debugging `doca_flow_grpc` — the DOCA-shipped gRPC remote-control
  surface in front of `doca-flow` that lets non-C++ clients (Python,
  Go, Rust, Java) program Flow pipes and entries over RPC instead of
  linking `libdoca_flow.so` directly. Trigger even when the user
  doesn't say 'doca-flow-grpc-server' or 'gRPC' — e.g. 'program Flow
  rules from Python on another host', 'remotely configure pipes on the
  BlueField', 'client times out connecting to the Flow server', 'where
  is the .proto for Flow', 'UNAUTHENTICATED / FAILED_PRECONDITION on a
  Flow RPC'. Route elsewhere for the underlying doca-flow API, generic
  gRPC tooling (protoc, language bindings), or DOCA install / BFB
  bring-up.
metadata:
  kind: tool
compatibility: >
  Requires DOCA on Linux (Ubuntu 22.04/24.04 or RHEL/SLES) with a
  BlueField DPU or ConnectX NIC. The `doca_flow_grpc` binary is a build
  artifact (install: false in tools/flow_grpc_server/meson.build, gated by
  flag_enable_grpc_support + flag_enable_grpc_flow_library) — NOT
  installed under a default DOCA path; build it from the DOCA source tree
  with gRPC enabled. Its `.proto` lives under libs/doca_flow/grpc/.
  Confirm Flow via `pkg-config doca-flow`.

DOCA Flow gRPC Server (`doca_flow_grpc`)

> **CRITICAL transport-security correction (Run-12 + R13).** The > shipped `doca_flow_grpc` / `doca_flow_grpc_client` > binaries hard-code the gRPC plaintext credentials surface: > the **server** uses **`grpc::InsecureServerCredentials()`** (the > C++ gRPC server-side API in `tools/flow_grpc_server/server/`); > the **C++ client** uses > **`grpc::InsecureChannelCredentials()`** (the C++ gRPC > client-side API; the client lives in > `libs/doca_flow/grpc/client/`, compiled into the > `doca_flow` library, NOT under `tools/flow_grpc_client/`); > the **Python > client** uses `grpc.aio.insecure_channel(...)`. Do NOT cite the > server-side string as `grpc::InsecureChannelCredentials()` — > that is the **client-side** API name and a Grep-against-source > verification will fail. There > is **no TLS, no mTLS, and no token-auth** knob on the shipped > control plane today. Any prose below (or in `CAPABILITIES.md` > / `TASKS.md`) that frames "mTLS / token auth / TLS posture" > as a configurable knob on **this** server is the bundle's > previous aspirational framing and is wrong against the shipped > source. Treat the server as **plaintext-on-a-trusted-segment > only**: it MUST be bound on a control-plane-only network > segment behind an external proxy, sidecar, or VPN > that itself enforces TLS + identity. Any "TLS / mTLS / token- > auth" discussion below is about the operator's external > hardening layer, NOT a knob on this binary. Routing for an > TLS / identity design discussion must stay on the selected > external proxy, sidecar, or VPN; never route it to a > shipped-today binary knob.

**Where to start:** This is a tool skill for standing up and operating `doca_flow_grpc`, the DOCA-shipped gRPC remote- control surface for `doca-flow`. Open [`TASKS.md`](TASKS.md) and start at [`## configure`](TASKS.md#configure) to decide whether a remote control plane is the right answer at all (vs talking to `libdoca_flow.so` directly), then [`## run`](TASKS.md#run) for the start → bind → one-client-smoke sequence, then [`## test`](TASKS.md#test) for the smoke-before-bulk loop that gates any RPC that mutates Flow / dataplane state. Open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what the gRPC contract surface looks like* (the `.proto` files shipped under the tool's source tree on the user's install), *which external proxy / sidecar / VPN protects the plaintext server*, *which language bindings the gRPC ecosystem covers*, or *how to interpret the server's own logs alongside the live Flow application's logs*. If DOCA is not installed, route to [`doca-setup`](../../doca-setup/SKILL.md) first; if the user has not stood up `doca-flow` yet, route to [`doca-flow`](../../libs/doca-flow/SKILL.md) FIRST — the gRPC server is a remote control plane on top of the Flow library, not a replacement for it.

Example questions this skill answers well

The CLASSES of `doca_flow_grpc` questions this skill is built to answer, each with one worked example. The class is the load-bearing piece; the worked example is one instance.

• **"Do I actually need a remote control plane for my Flow

pipeline, or should my client just link `libdoca_flow.so` directly?"** — worked example: *"my client is a Python service on a different host; can it program Flow rules remotely?"*. Answered by the *when-to-use-gRPC* decision in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the routing into

[`doca-flow`](../../libs/doca-flow/SKILL.md) when a direct library link is the better answer.

• **"Where is the gRPC contract surface actually defined on my

install?"** — worked example: *"I want to generate a Python client; where do I get the `.proto` file?"*. Answered by the *the-`.proto`-file-is-the-source-of-truth* rule in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the language-bindings discussion of standard gRPC tooling

(`protoc` + the language-specific gRPC plugin per the [official gRPC docs](https://grpc.io/docs/) on `grpc.io`).

• **"How do I harden the gRPC endpoint so it isn't an open

door into my dataplane?"** — worked example: *"the server is bound on `0.0.0.0`; what should I do before exposing it?"*. Answered by the *admin attack surface* posture in [`CAPABILITIES.md ## Safety policy`](CAPABILIT