doca-flow-grpc-server

DOCA Flow gRPC サーバー（doca_flow_grpc）

例

• 「Flow にリモートコントロールプレーンは本当に必要ですか？」 — これは対象範囲内です。クライアントを同じホスト上で 動かせる場合は、libdoca_flow.so への直接リンクを優先してください。
• 「インストール先の gRPC コントラクトはどこにありますか？」 — .proto が信頼できる唯一の情報源です。記憶を頼りに RPC を作り出さないでください。

手順

以下の読み込み順に従ってください。設定／実行／デバッグについてはタスク用コンパニオンを開いてください。gRPC を使う場面とエンドポイントのセキュリティ対策については、機能用コンパニオンを開いてください。コンパニオンファイルをすべて開く必要はありません。

重大なトランスポートセキュリティに関する訂正（Run-12 + R13）。 同梱されている doca_flow_grpc / doca_flow_grpc_client バイナリは、gRPC のプレーンテキスト認証情報インターフェイスをハードコードしています。 サーバーは grpc::InsecureServerCredentials()（tools/flow_grpc_server/server/ にある C++ gRPC サーバー側 API）を使用します。 C++ クライアントは grpc::InsecureChannelCredentials()（C++ gRPC クライアント側 API。クライアントは tools/flow_grpc_client/ ではなく、doca_flow ライブラリにコンパイルされる libs/doca_flow/grpc/client/ にあります）を使用します。 Python クライアントは grpc.aio.insecure_channel(...) を使用します。サーバー側の文字列を grpc::InsecureChannelCredentials() として記載しないでください。これはクライアント側の API 名であり、Grep によるソース検証で不合格になります。現時点で同梱されているコントロールプレーンには、TLS、mTLS、トークン認証の設定項目はありません。以下（または機能用コンパニオン／タスク用コンパニオン）の説明で、このサーバーの設定項目として「mTLS／トークン認証／TLS のセキュリティ対策」を扱っている場合、それはこの一式に以前あった将来的な構想にすぎず、同梱ソースの実態とは異なります。サーバーは信頼できるセグメント内でのみプレーンテキスト接続を許可するものとして扱ってください。サーバーは、TLS と ID を適用する外部プロキシ、サイドカー、または VPN の背後にある、コントロールプレーン専用のネットワークセグメントに必ずバインドしてください。以下の「TLS／mTLS／トークン認証」に関する説明は、オペレーターが外部で追加するセキュリティ強化レイヤーについてのものであり、このバイナリの設定項目ではありません。TLS／ID 設計に関する相談は、選択した外部プロキシ、サイドカー、または VPN に案内してください。同梱済みのバイナリにある設定項目へ案内してはいけません。

最初に確認する項目： このツールスキルは、DOCA に同梱されている doca-flow の gRPC リモート制御インターフェイス doca_flow_grpc の立ち上げと運用を扱います。タスク用コンパニオンを開き、まず ## configure から始めて、リモートコントロールプレーンが本当に適切な選択肢か（libdoca_flow.so に直接アクセスする場合と比較して）判断してください。次に ## run で起動 → バインド → 1 クライアントでのスモークテストの手順を確認し、続いて ## test で、Flow／データプレーンの状態を変更する RPC を実行する前に必ず行う、スモークテストから大量処理へ進むループを確認してください。gRPC のコントラクトインターフェイス（ユーザーのインストール環境にあるツールのソースツリー内に同梱された .proto ファイル）、プレーンテキストのサーバーを保護する外部プロキシ／サイドカー／VPN、gRPC エコシステムが対応する言語バインディング、またはサーバー自身のログと稼働中の Flow アプリケーションのログの読み解き方について質問された場合は、機能用コンパニオンを開いてください。DOCA がインストールされていない場合は、まず doca-setup/SKILL.md に案内してください。ユーザーがまだ doca-flow を立ち上げていない場合は、まず doca-flow/SKILL.md に案内してください。gRPC サーバーは Flow ライブラリ上のリモートコントロールプレーンであり、その代わりになるものではありません。

このスキルの使い方。 このファイルを読み、次に質問に必要な ## <name> 見出しをコンパニオンファイル内で検索し、そのセクション全体を読んでください。記載されたシンボルとコマンドだけを引用して、内容を漏れなく回答してください。ドキュメントを閲覧せず、doca-public-knowledge-map のエントリーポイントを使用してください。環境の確認は、ユーザーの DOCA ホストで実行するコマンドとして示してください。対象範囲外の依頼については、担当するスキルを示して、そこで回答を終えてください。

このスキルが適切に回答できる質問の例

このスキルが回答するように作られているdoca_flow_grpcの質問の種類と、それぞれの回答例を示します。重要なのは質問の種類であり、回答例はその一例です。

• 「Flowパイプラインにリモートコントロールプレーンは本当に必要ですか。それとも、クライアントからlibdoca_flow.soを直接リンクすればよいですか？」 — 回答例：「クライアントは別のホスト上で動作するPythonサービスです。リモートからFlowルールを設定できますか？」。能力に関する補足資料のgRPCを使う場面の判断基準と、直接ライブラリをリンクする方が適切な場合にdoca-flow/SKILL.mdへ案内することで回答します。
• 「インストール環境で、gRPCのコントラクトが定義されている場所はどこですか？」 — 回答例：「Pythonクライアントを生成したいのですが、.protoファイルはどこから入手できますか？」。能力に関する補足資料の*.protoファイルが唯一の信頼できる情報源*というルールと、grpc.ioの公式gRPCドキュメントに基づく、標準的なgRPCツール（protocと各言語向けのgRPCプラグイン）についての言語バインディングの説明で回答します。
• 「gRPCエンドポイントがデータプレーンへの無防備な入り口にならないように、どう強化すればよいですか？」 — 回答例：「サーバーが0.0.0.0でバインドされています。公開する前に何をすべきですか？」。能力に関する補足資料に記載された管理用の攻撃対象領域に対する方針と、タスクに関する補足資料に記載された外部からの保護やネットワークセグメントに関する判断で回答します。
• 「サーバーを全クライアントに公開する前に、クライアント1台でエンドツーエンドのスモークテストを行うにはどうすればよいですか？」 — 回答例：「Pythonクライアントでエンドポイントに接続できます。稼働中のFlowアプリケーションとの通信を確認するには、最初にどのRPCを実行すればよいですか？」。タスクに関する補足資料の、一括処理の前にスモークテストを行う手順と、能力に関する補足資料の、一括処理の前にスモークテストを行うルールで回答します。
• 「クライアントがサーバーに接続できません。サーバーが停止しているのか、エンドポイントが間違っているのか、外部プロキシとの不整合なのか、バージョンの不一致なのか、どう判断すればよいですか？」 — 回答例：「クライアントが接続時にタイムアウトします」。能力に関する補足資料の階層化されたエラー分類と、タスクに関する補足資料の段階的な切り分け手順で回答します。
• 「C++以外のクライアント（Python／Go／Rust）はgRPCコントラクトに適した形ですか。それとも、もっとシンプルな方法がありますか？」 — 回答例：「Rustクライアントを作りたいのですが、.protoから生成されるAPIはどのようなものですか？」。能力に関する補足資料の言語バインディングの説明と、標準的なgRPCツールの利用方法に関する案内で回答します。

対象読者

このスキルは、libdoca_flow.so を制御プロセスに直接リンクするのではなく、ネットワーク境界を越えて、C++ 以外のプロセスから実行中の DOCA Flow パイプラインをプログラムする必要がある外部オペレーター、コントロールプレーン開発者、AI エージェントを対象としています。具体的には、次のような読者です。

• BlueField のアドレス空間の外部から、BlueField 上の Flow ルールをプログラムする Python／Go／Rust クライアントを作成するコントロールプレーンエンジニア。
• BlueField 上で Flow を使用するサービスを実行しており、集中管理されたコントロールプレーンにリモート制御用のインターフェースを公開したいプラットフォームオペレーター。
• 周辺の doca-flow アプリケーションへのコード変更を提案する前に、*「このクライアント／このネットワーク位置から Flow ルールをプログラムできるか」*を切り分けるエージェント。

このスキルは、gRPC サーバーのソースコードをデバッグするユーザーを対象としていません。docs.nvidia.com にある公開中の DOCA Flow gRPC Server ガイドの代わりにはなりません。また、doca-flow API を学ぶためのものでもありません。この対象読者は doca-flow/SKILL.md を参照してください。

doca_flow_grpc は、DOCA ソースツリーからビルドされる単一の CLI バイナリ（tools/flow_grpc_server/meson.build 内の executable('doca_flow_grpc', ..., install: false)。flag_enable_grpc_support によって有効化されます）と、libs/doca_flow/grpc/ 以下にある付属の .proto コントラクトファイルで構成されます。ツールのソースツリー（server/、dpa_device/、packet_buffering/）によると、必要な構成では、パケットバッファリング／DPA 側のヘルパーと組み合わせて使用することもできます。このスキルは、バンドル内のほかのツール枠と同じ kind: tool の3ファイル構成（このスキル、機能の補足ファイル、タスクの補足ファイル）を使用します。このファイルの先頭にあるフロントマターには、すでに kind: tool と記載されています。（以前のバンドルの改訂版では、ここを「library three-file shape」としていました。この表現はフロントマターと矛盾していたため、修正されています。）

言語の範囲

このスキルでは、配布された .proto ファイルから生成される言語固有の gRPC プラグインを使用し、標準的な gRPC ツールが対応する各言語（Python、Go、C++、Rust、Java、Node.js、C#、Kotlin、Ruby、PHP、Dart）を対象に、デプロイ、設定、セキュリティ強化、クライアント側の起動を扱います（gRPC の言語サポートの一覧は grpc.io を参照してください）。サーバー自体は C++ と DOCA で構成されます。クライアントの言語は、標準の protoc プラグインセットのみを条件とし、制限されません。サーバーがプログラムする doca-flow API については、doca-flow/SKILL.md を参照してください。この API は C 言語向けです。

このスキルを読み込むタイミング

ユーザーが doca_flow_grpc を実行中の doca-flow アプリケーション（またはその前提条件）に対して起動し、C++ 以外のクライアントを接続する必要がある場合、またはエージェントがその作業を行う必要がある場合に、このスキルを読み込んでください。具体的には、次のような場合です。

• リモート gRPC コントロールプレーンが適切なインターフェースか（クライアントプロセスから libdoca_flow.so に直接リンクする場合と比較して）を判断するとき。
• 言語バインディングを使用するクライアントが適切なスタブを生成できるよう、ユーザーのインストール先にある .proto ファイルを特定するとき。
• デプロイのトランスポートセキュリティ方針とネットワークセグメントを決めるとき。注：配布されているサーバーは平文通信のみ対応しています（grpc::InsecureServerCredentials()）。TLS／mTLS／トークン認証はバイナリの設定項目ではありません。対応するプロキシ、サイドカー、VPN で処理する外部インフラストラクチャ上の課題です。また、平文のエンドポイントは、信頼された隔離済みセグメント内にとどめる必要があります。
• 確実に動作する Flow 環境と併せてサーバーを起動し、エンドポイントをフリートに公開する前に、クライアントを1つ使ってエンドツーエンドのスモークテストを行うとき。
• 階層化された分類に沿って、接続、バージョン、RPC の失敗を診断するとき。

一般的な DOCA の概要、doca-flow API の作業、DOCA のインストール、または一般的な gRPC ツールのために、このスキルを読み込まないでください。それらについては、grpc.io のドキュメントを直接参照してください。

このスキルが提供するもの

これは薄いローダーです。実質的な内容は、次の2つの補助ファイルにあります。

• capabilities の補助ファイル — doca_flow_grpc が公開する機能： doca-flow の前段にある gRPC リモート制御インターフェース、 .proto ファイルを正式な契約とするルール（ユーザーのインストール環境でツールのソース内に同梱されている .proto ファイルが正となります）、gRPC とライブラリの直接リンクのどちらを使うかの判断、言語バインディングの方針（標準的な gRPC ツールが対応するあらゆる言語を使用できます）、外部プロキシ／サイドカー／VPN およびネットワークセグメントの選択、同梱されている packet_buffering/ および dpa_device/ サブツリーに従ったパケットバッファリング／DPA 側のオプション、バージョンの対応関係（サーバーはリンク先の doca-flow ライブラリのバージョンに従います）、階層化されたエラー分類（サーバー未起動／サーバーのバインド失敗／外部レイヤーによる拒否／RPC 呼び出しエラー／Flow の前提条件未達／バージョン／横断的な問題）、可観測性の手段（サーバー自身のログ＋稼働中の Flow アプリケーションのログ＋RPC クライアントのステータスコード）、およびエンドポイントを管理者向けの攻撃対象領域として扱う安全性ポリシー。
• tasks の補助ファイル — 対象となるタスク動詞の手順ごとのワークフロー：install（セットアップに誘導。バイナリは gRPC サポートを有効にしてソースからビルドします）、configure（リモートと直接接続のどちらにするかを決め、外部プロキシ／サイドカー／VPN とネットワークセグメントを選択します）、build（インストールに誘導）、modify（拒否 — バイナリではなくデプロイメントを変更します）、run（起動 → バインド → スモークテスト）、test（クライアント側のスタブ生成手順を含む、スモークテストを先に行ってから一括処理するループ）、debug（階層的な診断手順）、use（キャプチャした gRPC サーバーセッションを利用する、エージェント側のワークフロー）、さらに Deferred task verbs ブロックと Command appendix。

このスキルでは、DOCA がすでにインストールされているホスト（または NGC DOCA コンテナが稼働しているホスト）に Flow ライブラリが存在し、プログラム対象となる doca-flow アプリケーションが動作しており、gRPC コントロールプレーンを公開することが重大なリスクを伴うことをオペレーターが認識しているものとします。

このスキルに意図的に含めていないもの

このスキルはエージェント向けガイダンスであり、サンプルやスクリプトのバンドルではありません。明確な境界を保つため、意図的に次の内容を含めていません。また、プルリクエストにも追加しないでください。

• RPC メソッド名、メッセージフィールドの一覧、デフォルトのエンドポイントパスをそのまま掲載したもの。 ユーザーのインストール環境でツールのソースツリー内に同梱されている .proto ファイルが正式な契約です。ここにコピーすると、スキルが特定のリリースに固定され、契約が進化したときに気づかれないまま古くなります。
• あらゆる言語の、あらかじめ用意されたクライアントコード。 言語固有の gRPC プラグインと同梱の .proto ファイルが契約です。ユーザーのインストール済みバージョンから生成したクライアントコードが適切な答えであり、特定時点のスナップショットに固定されたスタブではありません。
• あらかじめ用意された外部セキュリティレイヤーの設定。 CA、トークン、mTLS の設定は、選択したプロキシ、サイドカー、または VPN と、そのセキュリティレビューに属するものであり、doca_flow_grpc の範囲ではありません。
• gRPC エンドポイントを別のプロトコルに変換するラッパー、パーサー、スクリプト。エンドポイントはそのままのエンドポイントです。ユーザーが HTTP/JSON を望む場合、それはこのスキルの範囲外にある別の課題です。
• samples/、bindings/、reference/ サブツリー。 *「reference」*と明記したものでも誤解を招きます。オペレーターはビルド可能なものとして受け取るでしょう。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内か確認してください（ユーザーが実際に求めているのは、doca-flow のライブラリーを直接リンクすることでも、別の DOCA ライブラリーでもなく、その上に構築するリモート gRPC コントロールプレーンです）。
2. サーバーが公開する機能、.proto を契約とするルール、言語バインディングの仕組み、外部プロキシ／サイドカー／VPN とネットワークセグメントに関する判断、バージョンの提供状況、階層化されたエラーの表面、可観測性、安全性の方針については、関連する capabilities スキルを参照してください。
3. ドキュメントに記載された開始手順と、まとめて実行する前にスモークテストを行うワークフロー（install、configure、build、modify、run、test、debug、use）については、関連する tasks スキルを参照してください。

関連スキル

• doca-flow/SKILL.md — サーバーの gRPC 契約が薄いリモート制御ラッパーとして機能する基盤ライブラリーです。Pipe／entry／rule のセマンティクス、コミット前に検証するルール、Flow のカウンター／インスペクター機能については、すべてこちらを参照してください。
• doca-flow-tune/SKILL.md — Flow のチューニングツールです。Flow プログラムの変更が推奨された場合、その変更は周辺アプリケーション経由で適用するか、またはコントロールプレーンがリモートの場合は、この gRPC サーバーの RPC 機能を通じて適用できます。
• doca-public-knowledge-map/SKILL.md — docs.nvidia.com の公開 DOCA Flow gRPC Server ページや、その他の公開 DOCA ドキュメントへの案内に使用します。
• doca-version/SKILL.md — バージョンの取り扱いに関する規則を定めた正式な情報源です。このスキルの ## Version compatibility セクションは、その上に重ねる薄い補足です。
• doca-debug/SKILL.md — 分野横断的なデバッグ手順です。gRPC サーバーの障害は、ランタイム層でこの手順に沿って対応します。
• doca-setup/SKILL.md — 環境の準備、インストールの検証、NGC DOCA コンテナーの利用方法について説明します。
• doca-hardware-safety/SKILL.md — 分野横断的なハードウェア安全性のメタポリシーです。このスキルの ## Safety policy は、このメタポリシーを補足します。状態を変更する RPC は、データプレーンに影響を与える可能性がある変更として、メタポリシーに従う必要があります。