/doca-flow-grpc-server

DOCA Flow gRPC Server — Capabilities

Where to start: doca_flow_grpc is a remote-control gRPC surface in front of doca-flow. The pattern overview below names the recurring server-side questions. Pick the pattern first, then drill into the H2 that owns the substance. For the how of executing each pattern, jump to TASKS.md. For the underlying doca-flow API the server's RPCs program, see doca-flow CAPABILITIES.md.

This file is loaded by SKILL.md. It documents what state the server exposes, how the gRPC contract is defined and where the authoritative .proto files live, what transport posture the external proxy / sidecar / VPN owns, which versions it ships in, the layered error and observability surfaces, and the safety policy that treats the endpoint as an admin attack surface.

Pattern overview

Every doca_flow_grpc question this skill teaches resolves into one of FIVE patterns. The patterns are CLASSES — they apply across every doca-flow control-plane deployment, not one specific application.

Two cross-cutting rules that apply to every pattern above:

• The .proto file is the contract. Every concrete RPC name, message field name, and field type the agent quotes must come from the shipped .proto files on the user's installed version (or, equivalently, from the public DOCA Flow gRPC Server page on docs.nvidia.com for the same release). Inventing RPC names from generic gRPC patterns ("ListPipes", "AddRule") is the canonical hallucination failure for this skill.
• State-changing RPCs are dataplane-affecting. An RPC that creates / mutates / deletes pipes or entries does to Flow state exactly what a direct libdoca_flow.so call would do. The agent must label every RPC as read-only or state-changing and gate every state-changing RPC on a clean smoke per ## Safety policy.

Capabilities and modes

doca_flow_grpc is a single CLI binary built from the DOCA source tree (executable('doca_flow_grpc', ..., install: false), gated by flag_enable_grpc_support), plus the .proto files under libs/doca_flow/grpc/ that define its gRPC contract and (per the shipped packet_buffering/ and dpa_device/ source subtrees) optional companion components for configurations that need packet buffering or DPA-side helpers. The interaction model is operator starts the plaintext server with appropriate device + Flow + bind configuration behind the external security layer; clients dial through that layer and call the documented RPCs.

Remote-vs-direct decision

The first question the agent must surface before recommending this tool at all.

The downstream rule: do not default to gRPC because it sounds modern. A direct library link in the same process is simpler, faster, and has a smaller attack surface; gRPC is the right answer only when the deployment topology genuinely requires a network boundary.

The .proto file is the authoritative gRPC contract

The shipped DOCA install contains the .proto files that define every RPC method, every request / response message, and every field on the gRPC surface. Those files are the source of truth on the user's installed version; nothing else (not a public docs page snapshot, not agent memory, not a generic gRPC pattern) is.

The agent's rule:

• Locate the .proto files on the user's install (under the tool's source tree shipped with DOCA; the exact path is install-specific and the agent should not invent it).
• Generate client stubs with the standard gRPC tooling for the client language — protoc plus the language-specific gRPC plugin per the gRPC quickstart index on grpc.io.
• Cite the .proto file when naming an RPC method or a message field; never quote a name from prose or memory.

External security layer and network segment

CRITICAL (Run-12 + R13). The shipped doca_flow_grpc binary hard-codes grpc::InsecureServerCredentials() (gRPC C++ server-side API); the C++ doca_flow_grpc_client binary hard-codes grpc::InsecureChannelCredentials() (gRPC C++ client-side API); the Python client uses grpc.aio.insecure_channel(...). The substantive "no TLS / no mTLS / no token-auth" posture is identical across all three; the correct symbol name on the server side is InsecureServerCredentials, NOT InsecureChannelCredentials (a Grep against tools/flow_grpc_server/server/ will return the server-side symbol). The "Auth" and "TLS" concerns are NOT in-binary knobs — there is no shipped flag, config file, env var, or build option that turns on TLS or mTLS or token-auth on this server today. The only sound posture is plaintext-on-a-trusted-segment behind an external TLS/identity layer (a TLS-terminating reverse proxy, a service mesh sidecar, a WireGuard tunnel, etc.). The decision the operator makes is therefore: which external hardening layer will gate this plaintext endpoint — NOT which in-binary auth/TLS knob to flip.

The operator must choose the external protection and the network segment before exposing the endpoint:

If only a subset of RPCs should be reachable, enforce that subset in a capable external proxy that can inspect and allow specific gRPC methods. The shipped binary provides no per-method authorization knob; do not claim that it does.

Language bindings

gRPC is a multi-language ecosystem. The languages the standard gRPC tooling covers include — per the gRPC language support index on grpc.io — C++, Java, Python, Go, Ruby, C#, Node.js, Android, Objective-C, PHP, Dart, Kotlin, and (via community plugins) Rust. For any of those languages, the client is generated by protoc + the language-specific gRPC plugin from the shipped .proto files; this skill does not pin a "supported language" list of its own — the gRPC ecosystem's coverage is the contract.

Optional companion components

Per the shipped source tree, the tool can be paired with two optional companions:

• packet_buffering/ — a packet-buffering helper for configurations that need it. Whether to enable it is a deployment-shape decision that depends on the surrounding Flow application's traffic pattern.
• dpa_device/ — a DPA-side helper for configurations that involve DPA-offload paths on a DPA-capable device. Cross-references doca-dpa and doca-flow-dpa-perf for the underlying DPA programming model and performance surface.

The exact configuration field names and CLI shape live on the user's installed binary's --help plus the public DOCA Flow gRPC Server page on docs.nvidia.com.

Version compatibility

For the canonical DOCA version-detection chain, the four-way match rule, NGC container semantics, and the headers-win-over- docs rule, see doca-version. The body lives there; this skill does not duplicate it.

The doca_flow_grpc-specific overlay is:

• The server rides the doca-flow library version it links against. A doca-flow library *.so from one DOCA train paired with a gRPC server binary from another is a partial-install hazard per doca-version CAPABILITIES.md ## Version compatibility. The four-way match per doca-version TASKS.md ## test applies without modification.
• The .proto contract is versioned with the DOCA install. RPC method names, message fields, and field types can shift across DOCA releases. Clients generated from one release's .proto files cannot be assumed to work against a server binary from another release; if the contract changed, the client must be regenerated.
• Where it runs. The server runs on whichever side has the doca-flow library installed (host x86 / Arm, BlueField Arm, or NGC container with the Flow trace flavor present). The client can run anywhere with gRPC tooling for the client language plus network reachability to the server's endpoint.
• gRPC ecosystem versioning is independent of DOCA's versioning. Per the gRPC versioning policy on grpc.io, the gRPC libraries themselves track their own versions; the agent's rule is "use the gRPC library version your language ecosystem currently recommends, plus the .proto files from the user's DOCA install".

Error taxonomy

doca_flow_grpc's error surface is broader than a local-only tool because the tool both serves remote clients and exposes Flow state. The error layers the agent should distinguish, in escalating order:

1. Server-not-started. The Flow setup is in place but the gRPC server process is not running. Cause: the operator did not start the binary, the binary crashed, or a precondition (Flow library missing, device not bound) blocked startup. Routing: confirm DOCA is installed via doca-version TASKS.md ## configure and the Flow library is present per doca-flow TASKS.md ## test; confirm the binary's own logs.
2. Server-binding-failed. The init ran but the server could not bind the configured network address / port. Cause: another process holds the port, the configured address does not exist on the host, or the process lacks permission to bind it. Certificate and token failures belong to the external security layer, not this binary. The server's own error log is ground truth; do not guess. Routing: confirm the address / port against the operator's deployment config; route env-side issues to doca-setup ## debug.
3. External-layer-rejected. The client did not traverse the selected proxy, sidecar, or VPN. Diagnose that layer using its own logs and configuration; do not map its certificate, token, or policy failures onto doca_flow_grpc, and do not suggest an in-binary fix.
4. RPC-call-error. The client traversed the external layer and issued an RPC, but the server returned a gRPC status code other than OK. The right move is to match the status code to the documented RPC contract in the .proto files — INVALID_ARGUMENT means the request message is malformed; NOT_FOUND means the requested pipe / entry does not exist; FAILED_PRECONDITION means a Flow-side precondition (pipe not created, validate-before-commit not performed) blocked the operation. Routing for the Flow-side preconditions: doca-flow TASKS.md ## modify plus doca-flow CAPABILITIES.md ## Error taxonomy.
5. Flow-precondition-failed. The RPC was syntactically valid but the underlying Flow application is not in a state to accept it (port not started, pipe not created, another mutation in flight). The right move is the doca-flow side, not the gRPC server side.
6. Version. Cross-cutting partial-install / mixed- version layer per doca-version CAPABILITIES.md ## Version compatibility. Symptoms: the server's .proto contract does not match the client-side generated stubs (the client was generated from a different DOCA release's .proto); the server binary version disagrees with the Flow library version it links. Walk doca-version TASKS.md ## debug end-to-end.
7. Cross-cutting. All layers above are clean and the client still cannot use the server. The cause is below DOCA — driver, firmware, BlueField mode, network reachability, kernel-level firewall. Hand off to doca-debug ## debug and doca-setup ## debug.

The debug loop permits one diagnostic correction and one retry. If the same request remains non-green after that retry, stop, preserve the server log + client status + external-layer log, and escalate; do not widen access or continue retrying.

The gRPC server itself uses the cross-library DOCA_ERROR_* values when calling into doca-flow; the agent maps those into the layers above before quoting them.

Observability

doca_flow_grpc exposes three observability surfaces the agent should consult, in order:

• Server logs. The binary's own log output (per DOCA_LOG_LEVEL and the standard DOCA logging surface; see doca-programming-guide CAPABILITIES.md ## Observability) is the first source of truth for server-side errors. Bind start / bind failure / per-RPC accept and reject lines live here.
• Client-side gRPC status codes. Every failed RPC the client sees carries a standard gRPC status code per the gRPC status codes reference on grpc.io. The agent must quote the code (UNAVAILABLE / UNAUTHENTICATED / INVALID_ARGUMENT / NOT_FOUND / FAILED_PRECONDITION / etc.) verbatim; paraphrasing the code is the canonical lost-fidelity failure.
• The live Flow application's observability surface. Per doca-flow CAPABILITIES.md ## Observability, the Flow library exposes pipe / entry / counter / inspector state programmatically. When the gRPC RPC succeeds but the user's downstream behavior is wrong, this is where the diagnosis continues.

For the env-side counters that bound the deployment (link state, PCIe, IB), reach for doca-setup CAPABILITIES.md ## Observability.

Safety policy

Overlay on the bundle-wide hardware-safety meta-policy. The rules below are this skill's per-artifact overlay on the cross-cutting rules in doca-hardware-safety CAPABILITIES.md ## Safety policy (specifically ### Per-artifact overlay pattern). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.

Exposing doca_flow_grpc in production is a deliberately high-stakes posture — it is an admin attack surface attached to the dataplane:

• Treat the endpoint as a privileged surface. Bind it on a trusted segment (loopback, an internal management VLAN, a control-plane-only subnet) behind a capable external proxy, sidecar, or VPN that enforces TLS and identity before any client beyond a local smoke client. The shipped binary remains plaintext behind that layer. Recommend the operator confirm who can reach the endpoint before declaring it exposed.
• Transport security is external only. The proxy, sidecar, or VPN owns TLS, identity, and any RPC-subset policy. doca_flow_grpc exposes no certificate, token, TLS, or per-method authorization configuration.
• Smoke-before-bulk is mandatory. Before pointing a fleet of clients (or any production client) at the server, the agent runs the start → bind → one-client-smoke → read-only- RPC sequence in TASKS.md ## test. A server exposed without that sequence is a guess against a possibly-unbound endpoint, a possibly-misconfigured external protection layer, or a possibly-mismatched contract.
• State-changing RPCs are dataplane-affecting. Every RPC that creates / mutates / deletes pipes or entries does to Flow state exactly what a direct libdoca_flow.so call would do. The agent must label every RPC as read-only or state-changing and must NOT issue a state-changing RPC before a clean read-only smoke.
• Never widen access as a workaround. If a client cannot reach the server or an RPC is rejected, walk ## Error taxonomy once and retry once; then stop and escalate if still non-green. Do not bypass the external layer or widen the bind address to 0.0.0.0.
• Do not invent RPC names, message field names, or endpoint paths. The shipped .proto files on the user's installed version are the contract; prose-derived names are the most common hallucination failure for this skill.

Public-source pointer

The single canonical public source for doca_flow_grpc is the DOCA Flow gRPC Server page on docs.nvidia.com, reachable through doca-public-knowledge-map ## DOCA tools. The second authoritative source on the user's install is the shipped .proto file set under the tool's source tree. For generic gRPC ecosystem documentation (auth, status codes, language bindings, versioning), the canonical source is grpc.io — the public DOCA Flow gRPC Server page does not duplicate that ecosystem documentation. For the doca-flow API the server programs, see doca-flow plus the public DOCA Flow guide reached the same way.