Serveur gRPC DOCA Flow (doca_flow_grpc)

CORRECTIF CRITIQUE de sécurité transport (Run-12 + R13). Les binaires doca_flow_grpc / doca_flow_grpc_client livrés codent en dur la surface de credentials gRPC en texte brut : le serveur utilise grpc::InsecureServerCredentials() (l'API gRPC C++ côté serveur dans tools/flow_grpc_server/server/); le client C++ utilise grpc::InsecureChannelCredentials() (l'API gRPC côté client C++; le client se trouve dans libs/doca_flow/grpc/client/, compilé dans la bibliothèque doca_flow, NON sous tools/flow_grpc_client/); le client Python utilise grpc.aio.insecure_channel(...). Ne citez PAS la chaîne côté serveur comme grpc::InsecureChannelCredentials() — c'est le nom de l'API côté client et une vérification par grep sur les sources échouera. Il n'y a pas de TLS, pas de mTLS, et pas de knob d'auth par token sur le plan de contrôle livré aujourd'hui. Tout texte ci-dessous (ou dans CAPABILITIES.md / TASKS.md) qui présente « mTLS / auth par token / posture TLS » comme un knob configurable sur ce serveur relève du cadrage aspirationnel précédent du bundle et est faux par rapport à la source livrée. Traitez le serveur comme texte brut-sur-segment-de-confiance-uniquement : il DOIT être lié sur un segment réseau réservé au plan de contrôle derrière un pare-feu externe / VPN / bastion renforcé qui lui-même applique TLS + identité. Toute discussion « TLS / mTLS / token- auth » ci-dessous concerne la couche de renforcement externe de l'opérateur, NON un knob sur ce binaire. Le routage pour une discussion de conception TLS / auth interne au binaire doit le dire explicitement et acheminer l'utilisateur vers un framework gRPC générique (gRPC auth concepts) pour une conception d'état futur, non vers un knob livré aujourd'hui.

Par où commencer : c'est une skill outil pour déployer et exploiter doca_flow_grpc, la surface de contrôle à distance gRPC livrée par DOCA pour doca-flow. Ouvrez TASKS.md et commencez à ## configure pour décider si un plan de contrôle à distance est la bonne réponse (plutôt que de parler à libdoca_flow.so directement), puis ## run pour la séquence démarrage → liaison → smoke-test-un-client, puis ## test pour la boucle smoke-avant-volume qui valide tout RPC qui mute l'état Flow / dataplane. Ouvrez CAPABILITIES.md quand la question est à quoi ressemble la surface de contrat gRPC (les fichiers .proto livrés sous l'arborescence source de l'outil sur l'installation de l'utilisateur), comment la décision de posture auth / TLS est prise, quels bindings de langage l'écosystème gRPC couvre, ou comment interpréter les logs du serveur aux côtés des logs de l'application Flow en direct. Si DOCA n'est pas installé, routez vers doca-setup d'abord; si l'utilisateur n'a pas encore déployé doca-flow, routez vers doca-flow D'ABORD — le serveur gRPC est un plan de contrôle à distance au-dessus de la bibliothèque Flow, pas un remplacement.

Exemples de questions auxquelles cette skill répond bien

Les CLASSES de questions doca_flow_grpc que cette skill est construite pour répondre, chacune avec un exemple travaillé. La classe est la pièce porteuse; l'exemple travaillé est une instance.

• « Ai-je vraiment besoin d'un plan de contrôle à distance pour mon pipeline Flow, ou mon client devrait-il juste lier libdoca_flow.so directement ? » — exemple travaillé : « mon client est un service Python sur un hôte différent; peut-il programmer les règles Flow à distance ? ». Répondu par la décision quand-utiliser-gRPC dans CAPABILITIES.md ## Capabilities and modes
  • le routage vers doca-flow quand un lien de bibliothèque direct est la meilleure réponse.
• « Où la surface de contrat gRPC est-elle vraiment définie sur mon installation ? » — exemple travaillé : « je veux générer un client Python; où j'obtiens le fichier .proto ? ». Répondu par la règle le-fichier-.proto-est-la-source-de-vérité dans CAPABILITIES.md ## Capabilities and modes
  • la discussion sur les bindings de langage de l'outillage gRPC standard (protoc + le plugin gRPC spécifique au langage par la documentation gRPC officielle sur grpc.io).
• « Comment renforcer le endpoint gRPC pour qu'il ne soit pas une porte ouverte dans mon dataplane ? » — exemple travaillé : « le serveur est lié sur 0.0.0.0; que dois-je faire avant de l'exposer ? ». Répondu par la posture admin attack surface dans CAPABILITIES.md ## Safety policy
  • la décision auth / TLS / segment-réseau dans TASKS.md ## configure.
• « Comment je teste le smoke d'UN client bout-en-bout avant d'ouvrir le serveur à la flotte ? » — exemple travaillé : « mon client Python peut contacter le endpoint; quel est le premier RPC que j'exécute pour prouver qu'il parle à l'application Flow en direct ? ». Répondu par la boucle smoke-avant-volume dans TASKS.md ## test + CAPABILITIES.md ## Safety policy règle smoke-avant-volume.
• « Mon client ne peut pas atteindre le serveur — le serveur est-il en panne, le mauvais endpoint, un désalignement TLS / auth, ou un désalignement de version ? » — exemple travaillé : « le client expiration de délai lors de la connexion ». Répondu par la taxonomie d'erreur en couches dans CAPABILITIES.md ## Error taxonomy
  • l'échelle en couches dans TASKS.md ## debug.
• « Mon client non-C++ (Python / Go / Rust) est-il vraiment la bonne forme pour le contrat gRPC, ou existe-t-il un chemin plus clair ? » — exemple travaillé : « je veux un client Rust; à quoi ressemble l'API générée par .proto ? ». Répondu par la discussion sur les bindings de langage dans CAPABILITIES.md ## Capabilities and modes
  • le routage via l'outillage gRPC standard.

Public

Cette skill sert les opérateurs externes, les développeurs de plan de contrôle, et les agents IA qui ont besoin de programmer un pipeline DOCA Flow en cours d'exécution depuis un processus non-C++ à travers une limite réseau plutôt que de lier libdoca_flow.so directement dans le processus de contrôle. Concrètement :

• Un ingénieur de plan de contrôle écrivant un client Python / Go / Rust qui programme les règles Flow sur un BlueField depuis l'extérieur de l'espace d'adressage du BlueField.
• Un opérateur de plateforme exécutant un service Flow-utilisant sur BlueField qui veut exposer une surface de contrôle à distance à un plan de contrôle centralisé.
• Un agent IA pilotant l'étape de triage « puis-je programmer ces règles Flow depuis ce client / cette position réseau » avant de recommander un changement de code dans l'application doca-flow environnante.

Ce n'est pas pour les utilisateurs déboguant le code source du serveur gRPC, pas un substitut pour le guide public en direct DOCA Flow gRPC Server sur docs.nvidia.com, et pas l'endroit pour apprendre l'API doca-flow — ce public appartient à doca-flow.

doca_flow_grpc est un unique binaire CLI construit à partir de l'arborescence source DOCA (executable('doca_flow_grpc', ..., install: false) dans tools/flow_grpc_server/meson.build, bloqué par flag_enable_grpc_support), plus ses fichiers de contrat .proto compagnons sous libs/doca_flow/grpc/; selon l'arborescence source de l'outil (server/, dpa_device/, packet_buffering/) l'outil peut aussi être jumelé avec un helper côté packet-buffering / DPA sur les configurations qui en ont besoin. La skill utilise la même forme trois-fichiers kind: tool (SKILL.md + CAPABILITIES.md + TASKS.md) que le reste de l'emplacement outil du bundle utilise — front matter au début de ce fichier dit déjà kind: tool. (Les révisions antérieures du bundle disaient « forme trois-fichiers de bibliothèque » ici; cette formulation était intrinsèquement incohérente avec le front matter et est corrigée.)

Portée de langage

Cette skill gouverne le déploiement, la configuration, le renforcement, et la bring-up côté client à travers les langages que l'outillage gRPC standard couvre — Python, Go, C++, Rust, Java, Node.js, C#, Kotlin, Ruby, PHP, Dart — via le plugin gRPC spécifique au langage généré à partir des fichiers .proto livrés (voir l'index gRPC language support sur grpc.io). Le serveur lui-même est C++ + DOCA; les langages clients sont ouverts, bloqués uniquement par l'ensemble de plugins protoc standard. Pour l'API doca-flow que le serveur programme, voir doca-flow — cette surface est en langage C.

Quand charger cette skill

Chargez cette skill quand l'utilisateur est — ou l'agent a besoin de — déployer doca_flow_grpc contre une application doca-flow en cours d'exécution (ou ses pré-conditions) et connecter un client non-C++ à celle-ci. Concrètement :

• Décider si un plan de contrôle gRPC à distance est la bonne surface (vs un lien direct libdoca_flow.so dans le processus client).
• Localiser les fichiers .proto sur l'installation de l'utilisateur pour qu'un client avec binding de langage puisse générer les stubs appropriés.
• Décider la posture de sécurité transport du déploiement et le segment réseau. NOTE : le serveur livré est texte-brut-uniquement (grpc::InsecureServerCredentials()); TLS / mTLS / token-auth ne sont PAS des knobs de configuration binaire — ils sont des préoccupations d'infrastructure externe (p. ex. un proxy mTLS / sidecar) et le endpoint texte brut doit rester sur un segment isolé et de confiance.
• Déployer le serveur aux côtés d'une configuration Flow en bon état et faire un smoke-test d'un client bout-en-bout avant d'exposer le endpoint à la flotte.
• Diagnostiquer un échec de connexion / version / RPC via la taxonomie en couches.

Ne pas charger cette skill pour une orientation DOCA générale, du travail sur l'API doca-flow, l'installation DOCA, ou l'outillage gRPC général (utilisez la documentation grpc.io directement pour ceux-là).

Ce que cette skill fournit

C'est un thin loader. Le matériel substantiel vit dans deux fichiers compagnons :

• CAPABILITIES.md — ce que doca_flow_grpc expose : la surface de contrôle à distance gRPC en face de doca-flow, la règle fichiers-.proto-comme-contrat-faisant-autorité (les fichiers .proto livrés sous la source de l'outil sur l'installation de l'utilisateur sont la source de vérité), la décision quand-utiliser- gRPC-vs-lien-de-bibliothèque-direct, l'histoire des language- bindings (n'importe quel langage que l'outillage gRPC standard couvre), l'axe de décision auth / TLS / segment-réseau, l'option côté packet-buffering / DPA par les sous-arbres packet_buffering/ et dpa_device/ livrés, l'overlay de version (le serveur utilise la version de la bibliothèque doca-flow qu'il lie), la taxonomie d'erreur en couches (serveur-non-démarré / serveur-liaison-échouée / TLS-ou-auth- rejeté / erreur-appel-RPC / précondition-Flow-échouée / version / cross-cutting), la surface d'observabilité (les logs du serveur + les logs de l'application Flow en direct + les codes de statut du client RPC), et la politique de sécurité qui traite le endpoint comme une surface d'attaque admin.
• TASKS.md — workflows étape-par-étape pour les verbes de tâche in-scope : install (routez vers setup; le binaire est construit à partir de la source avec support gRPC activé), configure (décidez à-distance-vs-direct, choisissez auth / TLS, choisissez le segment réseau), build (routez vers install), modify (refusez — modifiez le déploiement, non le binaire), run (démarrage → liaison → smoke), test (la boucle smoke-avant-volume avec l'étape de génération de stub côté client), debug (l'échelle de diagnostic en couches), use (le workflow côté agent pour consommer une session serveur gRPC capturée), plus un bloc Deferred task verbs et un Command appendix.

La skill suppose un hôte où DOCA est déjà installé (ou le conteneur NGC DOCA est en cours d'exécution) avec la bibliothèque Flow présente, une application doca-flow en bon état pour programmer, et la prise de conscience de l'opérateur que l'exposition d'un plan de contrôle gRPC est une posture à fort enjeu.

Ce que cette skill ne livre délibérément pas

Cette skill est une guidance d'agent, non pas un bundle d'échantillons ou de scripts. Pour tenir la limite propre, elle ne contient délibérément pas — et les pull requests ne doivent pas ajouter :

• Noms de méthode RPC verbatim, inventaires de champ de message, ou chemins d'endpoint par défaut. Les fichiers .proto livrés sous l'arborescence source de l'outil sur l'installation de l'utilisateur sont le contrat faisant autorité; les copier ici épingle la skill à une release et pourrit silencieusement quand le contrat évolue.
• Code client pré-cuit dans n'importe quel langage. Le plugin gRPC spécifique au langage + les fichiers .proto livrés sont le contrat; le code client généré à partir d'eux sur la version installée de l'utilisateur est la bonne réponse, pas un stub épinglé à une snapshot.
• Une posture auth / TLS pré-cuite (quel CA, quelle source de token, quelle configuration mTLS). Cette posture est une décision d'environnement de déploiement — routez-la vers l'examen de sécurité de l'opérateur et la politique de sécurité.
• Wrappers, parsers, ou scripts qui proxifient le endpoint gRPC dans un autre protocole. Le endpoint est le endpoint; si un utilisateur veut HTTP/JSON à la place, c'est une préoccupation séparée hors de la portée de cette skill.
• Un sous-arbre samples/, bindings/, ou reference/. Même un étiqueté « reference » est trompeur : les opérateurs le liront comme compilable.

Ordre de chargement

1. Lisez d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est in-scope (l'utilisateur veut réellement un plan de contrôle gRPC à distance au-dessus de doca-flow, pas un lien de bibliothèque direct ou une autre bibliothèque DOCA).
2. Pour ce que le serveur expose, la règle .proto-comme-contrat, l'histoire des language-bindings, la décision auth / TLS / segment-réseau, la disponibilité de version, la surface d'erreur en couches, l'observabilité, et la posture de sécurité, voir CAPABILITIES.md.
3. Pour la séquence de démarrage documentée et le workflow smoke-avant-volume — install, configure, build, modify, run, test, debug, use — voir TASKS.md.

Skills associées

• doca-flow — la bibliothèque de base dont le contrat gRPC du serveur est un thin wrapper de contrôle à distance. La sémantique pipe / entry / rule, la règle validate-avant-commit, la surface du compteur / inspecteur Flow vivent tous là.
• doca-flow-tune — l'outil de tuning Flow. Quand un changement de programme Flow est recommandé, le changement peut être appliqué via l'application environnante ou — quand le plan de contrôle est à distance — via la surface RPC de ce serveur gRPC.
• doca-public-knowledge-map — routage vers la page publique DOCA Flow gRPC Server sur docs.nvidia.com et le reste de l'ensemble de documentation DOCA public.
• doca-version — règles de gestion de version canoniques. La section ## Version compatibility dans cette skill est un thin overlay au-dessus.
• doca-debug — l'échelle de debug cross-cutting. Les défaillances du serveur gRPC s'acheminent dans l'échelle au niveau runtime.
• doca-setup — préparation d'env, vérification d'installation, et le chemin du conteneur NGC DOCA.
• doca-hardware-safety — la meta-politique de sécurité matérielle cross-cutting dont la section ## Safety policy de cette skill est un overlay. Tout RPC de changement d'état est un changement potentiel affectant le dataplane et doit respecter la meta-politique.