doca-flow-grpc-server

# DOCA Flow gRPC Server (`doca_flow_grpc`) ## Examples - **"Do I actually need a remote control plane for Flow?"** — this is in scope. Prefer a direct `libdoca_flow.so` link when the client can live on the same host. - **"Where is the gRPC contract on my install?"** — the `.proto` is the source of truth; do not invent RPCs from memory. ## Instructions Follow Loading order below. Open the tasks companion for configure / run / debug. Open the capabilities companion for when-to-use-gRPC and endpoint posture. Do not open every companion file. > **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 the capabilities companion > / the tasks companion) 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 the tasks companion and start at `## configure` to decide whether a remote control plane is the right answer at all (vs talking to `libdoca_flow.so` directly), then `## run` for the start → bind → one-client-smoke sequence, then `## test` for the smoke-before-bulk loop that gates any RPC that mutates Flow / dataplane state. Open the capabilities companion 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. **How to use this skill.** Read this file, then search the companion file for the `## <name>` heading the question needs and read that whole section. Answer completely from it, quoting only its symbols and commands. Do not browse docs; use the entry points in `doca-public-knowledge-map`. Give environment checks as commands for the user's DOCA host. For out-of-scope requests, name the skill that owns them and stop. ## 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 the capabilities companion + 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 the capabilities companion + 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 the capabilities companion + the external protection / network-segment decision in the tasks companion. - **"How do I smoke ONE client end-to-end before opening the server to the fleet?"** — worked example: *"my Python client can dial the endpoint; what is the first RPC I run to prove it talks to the live Flow application?"*. Answered by the smoke-before-bulk loop in the tasks companion + the capabilities companion smoke-before-bulk rule. - **"My client cannot reach the server — is the server down, the wrong endpoint, an external-proxy mismatch, or a version mismatch?"** — worked example: *"the client times out connecting"*. Answered by the layered error taxonomy in the capabilities companion + the layered ladder in the tasks companion. - **"Is my non-C++ client (Python / Go / Rust) actually the right shape for the gRPC contract, or is there a cleaner path?"** — worked example: *"I want a Rust client; what does the `.proto`-generated API look like?"*. Answered by the language-bindings discussion in the capabilities companion + the routing through standard gRPC tooling. ## Audience This skill serves **external operators, control-plane developers, and AI agents who need to program a running DOCA Flow pipeline from a non-C++ process across a network boundary** instead of linking `libdoca_flow.so` directly into the controlling process. Concretely: - A control-plane engineer writing a Python / Go / Rust client that programs Flow rules on a BlueField from outside the BlueField's address space. - A platform operator running a Flow-using service on BlueField who wants to expose a remote-control surface to a centralized control plane. - An AI agent driving the *"can I program these Flow rules from this client / this network position"* triage step before recommending a code change to the surrounding doca-flow application. It is **not** for users debugging the gRPC server's source code, **not** a substitute for the live public DOCA Flow gRPC Server guide on `docs.nvidia.com`, and **not** the place to learn the `doca-flow` API — that audience belongs in [`doca-flow`](../../libs/doca-flow/SKILL.md). `doca_flow_grpc` is a **single CLI binary built from the DOCA source tree** (`executable('doca_flow_grpc', ..., install: false)` in `tools/flow_grpc_server/meson.build`, gated by `flag_enable_grpc_support`), plus its companion `.proto` contract files under `libs/doca_flow/grpc/`; per the tool's source tree (`server/`, `dpa_device/`, `packet_buffering/`) the tool can also be paired with a packet-buffering / DPA-side helper on configurations that need them. The skill uses the same `kind: tool` three-file shape (this skill + the capabilities companion + the tasks companion) the rest of the bundle's tool slot uses — front matter at the top of this file already says `kind: tool`. (Prior bundle revisions said "library three-file shape" here; that wording was internally inconsistent with the front matter and is corrected.) ## Language scope This skill governs deployment, configuration, hardening, and client-side bring-up across the languages standard gRPC tooling covers — Python, Go, C++, Rust, Java, Node.js, C#, Kotlin, Ruby, PHP, Dart — via the language-specific gRPC plugin generated from the shipped `.proto` files (see the [gRPC language support](https://grpc.io/docs/languages/) index on `grpc.io`). The server itself is C++ + DOCA; the client languages are open, gated only by the standard `protoc` plugin set. For the `doca-flow` API the server programs, see [`doca-flow`](../../libs/doca-flow/SKILL.md) — that surface is C-language. ## When to load this skill Load this skill when the user is — or the agent needs to — bring up `doca_flow_grpc` against a running `doca-flow` application (or its preconditions) and connect a non-C++ client to it. Concretely: - Deciding whether a remote gRPC control plane is the right surface (vs a direct `libdoca_flow.so` link in the client process). - Locating the `.proto` files on the user's install so a language-binding client can generate the appropriate stubs. - Deciding the deployment's transport-security posture and network segment. NOTE: the shipped server is plaintext-only (`grpc::InsecureServerCredentials()`); TLS / mTLS / token-auth are NOT binary configuration knobs — they are external infrastructure concerns handled by a capable proxy, sidecar, or VPN, and the plaintext endpoint must stay on a trusted, isolated segment. - Standing up the server alongside a known-good Flow setup and smoke-testing one client end-to-end before exposing the endpoint to the fleet. - Diagnosing a connect / version / RPC failure through the layered taxonomy. Do **not** load this skill for general DOCA orientation, `doca-flow` API work, DOCA install, or general gRPC tooling (use the [grpc.io](https://grpc.io/) docs directly for those). ## What this skill provides This is a **thin loader**. Substantive material lives in two companion files: - the capabilities companion — what `doca_flow_grpc` exposes: the gRPC remote-control surface in front of `doca-flow`, the `.proto`-files-as-authoritative-contract rule (the shipped `.proto` files under the tool's source on the user's install are the source of truth), the *when-to-use- gRPC vs direct-library-link* decision, the language- bindings story (any language standard gRPC tooling covers), the external proxy / sidecar / VPN and network-segment decision, the packet-buffering / DPA-side option per the shipped `packet_buffering/` and `dpa_device/` subtrees, the version overlay (server rides the `doca-flow` library version it links against), the layered error taxonomy (server-not-started / server-binding-failed / external-layer- rejected / RPC-call-error / Flow-precondition-failed / version / cross-cutting), the observability surface (the server's own logs + the live Flow application's logs + the RPC client's status codes), and the safety policy that treats the endpoint as an admin attack surface. - the tasks companion — step-by-step workflows for the in-scope task verbs: `install` (route to setup; binary is built from source with gRPC support enabled), `configure` (decide remote-vs-direct, pick the external proxy / sidecar / VPN and network segment), `build` (route to install), `modify` (refuse — modify the deployment, not the binary), `run` (start → bind → smoke), `test` (the smoke-before-bulk loop with the client-side stub generation step), `debug` (the layered diagnosis ladder), `use` (the agent-side workflow for consuming a captured gRPC server session), plus a `Deferred task verbs` block and a `Command appendix`. The skill assumes a host where DOCA is already installed (or the NGC DOCA container is running) with the Flow library present, a working `doca-flow` application to program against, and the operator's awareness that exposing a gRPC control plane is a high-stakes posture. ## What this skill deliberately does not ship This skill is **agent guidance**, not a samples or scripts bundle. To keep the boundary clean, it deliberately does not contain — and pull requests should not add: - **Verbatim RPC method names, message field inventories, or default endpoint paths.** The `.proto` files shipped under the tool's source tree on the user's install are the authoritative contract; copying them here pins the skill to one release and silently rots when the contract evolves. - **Pre-baked client code in any language.** The language-specific gRPC plugin + the shipped `.proto` files are the contract; client code generated from them on the user's installed version is the right answer, not a stub pinned to a snapshot. - **A pre-baked external security-layer configuration.** CA, token, and mTLS configuration belong to the selected proxy, sidecar, or VPN and its security review, never to `doca_flow_grpc`. - **Wrappers, parsers, or scripts** that proxy the gRPC endpoint into another protocol. The endpoint is the endpoint; if a user wants HTTP/JSON instead, that is a separate concern outside this skill's scope. - **A `samples/`, `bindings/`, or `reference/` subtree.** Even one labeled *"reference"* is misleading: operators will read it as buildable. ## Loading order 1. Read this skill first to confirm the user's question is in scope (the user actually wants a remote gRPC control plane on top of `doca-flow`, not a direct library link or a different DOCA library). 2. **For what the server exposes, the `.proto`-as-contract rule, the language-bindings story, the external proxy / sidecar / VPN and network-segment decision, version availability, the layered error surface, observability, and safety posture, see the capabilities companion.** 3. **For the documented start sequence and the smoke-before-bulk workflow — `install`, `configure`, `build`, `modify`, `run`, `test`, `debug`, `use` — see the tasks companion.** ## Related skills - [`doca-flow`](../../libs/doca-flow/SKILL.md) — the **base library** the server's gRPC contract is a thin remote- control wrapper over. Pipe / entry / rule semantics, the validate-before-commit rule, the Flow counter / inspector surface all live there. - [`doca-flow-tune`](../doca-flow-tune/SKILL.md) — the Flow tuning tool. When a Flow-program change is recommended, the change can be applied through the surrounding application or — when the control plane is remote — through this gRPC server's RPC surface. - [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md) — routing to the public DOCA Flow gRPC Server page on `docs.nvidia.com` and the rest of the public DOCA documentation set. - [`doca-version`](../../doca-version/SKILL.md) — canonical version-handling rules. The `## Version compatibility` section in this skill is a thin overlay on top. - [`doca-debug`](../../doca-debug/SKILL.md) — the cross-cutting debug ladder. gRPC server failures route into the ladder at the runtime layer. - [`doca-setup`](../../doca-setup/SKILL.md) — env preparation, install verification, and the NGC DOCA container path. - [`doca-hardware-safety`](../../doca-hardware-safety/SKILL.md) — the cross-cutting hardware-safety meta-policy this skill's `## Safety policy` overlays. Any state-changing RPC is a potential dataplane-affecting change and must respect the meta-policy.