VSS Warehouse — Helm Deploy

N'utilisez pas cette skill pour :

• Le déploiement Docker Compose warehouse — utilisez references/warehouse.md de vss-deploy-profile ; elle détient la table de mapping HARDWARE_PROFILE → GPU et la sémantique de stream-cap blueprint_config.yml que cette skill réutilise.
• Les profils Helm non-warehouse (base, search, lvs, alerts) — ils n'ont pas de stream cap GPU-aware bp-configurator ; déployez-les selon leurs propres README de chart.
• Les opérations runtime (ajout de caméras, requête sur les analytiques comportementales) — utilisez vss-manage-alerts / vss-query-analytics sur le déploiement en cours d'exécution.

Pourquoi cela existe

Docker Compose plafonne NUM_STREAMS par GPU automatiquement lors du déploiement warehouse : le configurateur lit la table max_streams_supported de deploy/docker/industry-profiles/warehouse-operations/blueprint-configurator/blueprint_config.yml pour le HARDWARE_PROFILE et le mode détectés, et limite final_stream_count = min(NUM_STREAMS, max_streams_supported).

Les charts Helm (deploy/helm/industry-profiles/warehouse-operations/warehouse-{2d,3d,mv3dt}-app) ne le font pas — leur bp-configurator.env embarque un NUM_STREAMS fixe et ne définit jamais HARDWARE_PROFILE du tout (ENABLE_PROFILE_CONFIGURATOR=false). Un utilisateur qui demande plus de streams que le GPU peut supporter n'obtient aucune protection. Cette skill comble cette lacune en calculant le même plafond que Compose appliquerait et en l'écrivant dans un fichier de valeurs-override Helm avant l'installation.

Scripts disponibles

Ce script n'a pas de dépendance skill/agent — un utilisateur qui ne veut pas utiliser cette skill peut l'exécuter directement (python3 compute_stream_cap.py --mode 2d --num-streams 8) et passer le fichier généré à helm upgrade/install -f lui-même.

Instructions

1. Précheck du cluster et des entrées requises avant de toucher Helm — ne supposez pas qu'un cluster neuf a déjà ceux-ci. Exécutez chaque vérification et rapportez pass/fail à l'utilisateur :

   kubectl cluster-info                         # cluster accessible
   kubectl get nodes                             # tous les nœuds Ready
   kubectl get storageclass                      # une StorageClass existe
   kubectl get nodes -o jsonpath='{.items[*].status.allocatable.nvidia\.com/gpu}{"\n"}'
                                                  # non-vide -> GPU Operator a enregistré les GPUs
   helm version --short                           # Helm 3.x

   Demandez aussi si l'utilisateur a déjà une clé API NGC — cela ne peut pas être vérifié depuis l'état du cluster, seulement demandé.

   En cas d'échec, ne signalez pas simplement le README à l'utilisateur et n'arrêtez pas — donnez-lui le correctif réel, copié depuis le README du chart, et proposez de l'exécuter pour lui :

   • Pas de StorageClass → relayez l'extrait d'installation local-path-provisioner + kubectl patch storageclass du README warehouse-<mode>-app §Prérequis (option bare-metal) — ou demandez quelle StorageClass ils envisagent d'utiliser s'ils en ont déjà une en tête.
   • Pas d'allocatable nvidia.com/gpu → relayez les étapes d'installation NVIDIA GPU Operator du §Prérequis (liens vers le guide de démarrage GPU Operator) et les versions de pilote recommandées listées là.
   • Cluster inaccessible / nœuds pas Ready → cela, l'utilisateur doit le corriger en dehors de Helm/cette skill entièrement ; dites-le clairement plutôt que de suggérer un correctif au niveau du chart.
   • Pas de clé API NGC → pointez vers §Required secrets du README du chart pour savoir comment créer le secret d'extraction, ne dites pas simplement « obtenez une clé API NGC ».

   Procédez à l'étape 2 seulement une fois que le cluster/StorageClass/GPU-Operator/Helm passent tous et que l'utilisateur a confirmé avoir une clé API NGC — une installation commencée avant cela échouera à mi-chemin d'une façon plus difficile à déboguer que de la détecter ici.

2. Demandez ingress vs. NodePort — cela détermine à la fois ce qui est installé dans cette étape et quelle commande d'installation est utilisée à l'étape 6, donc résolvez-le avant d'aller plus loin, ne définissez pas silencieusement l'un ou l'autre par défaut :

   • Ingress (nécessaire hors-cluster / pour un nom d'hôte stable) → vérifiez si un contrôleur ingress est déjà installé (kubectl get ingressclass). Sinon, relayez l'extrait d'installation haproxy-ingress du README warehouse-<mode>-app §"Install the ingress controller" et proposez de l'exécuter. Notez que c'est une étape unique, par cluster, pas par application.
   • NodePort (le plus simple pour un déploiement local/single-node rapide, aucun contrôleur ingress nécessaire) → dites à l'utilisateur que le chart embarque values-nodeport.yaml pour cela — la commande d'installation à l'étape 6 passe à -f values-nodeport.yaml mis en couches sous le fichier stream-cap, et les URLs de service se déplacent à <NODE_IP>:<port> au lieu de <NODE_IP>/<path>. Voir §"No ingress controller: NodePort" et §URLs du README du chart pour les ports exacts. Si l'utilisateur n'a pas dit lequel il veut et qu'il n'y a pas de signal clair (par ex. « juste le faire fonctionner localement » implique NodePort ; « l'exposer pour l'équipe » implique Ingress), demandez plutôt que de deviner.

3. Déterminez le mode et si vous devez activer les Alerts :

   • Mode. Utilisez 2d, 3d, ou mv3dt si la demande en nomme déjà un. Sinon demandez — ne devinez pas :
     • 2d — détection et suivi d'objets 2D.
     • 3d — suivi 3D multi-caméra RTVI-CV-3D autonome / sur entrées calibrées.
     • mv3dt — profil warehouse Multi-View 3D Tracking. A aussi besoin que rtvi.vss-rtvi-cv.standaloneWarehouse.mv3dt.fusion.maxExpectedSensors soit défini au nombre de streams effectif à l'étape 6/7 (par défaut 4) — c'est le paramètre de compte de caméra de la fusion BEV elle-même, séparé de NUM_STREAMS/syncFileCount, et le script stream-cap ne le touche pas.
   • Alerts. Pas un quatrième mode — une surcharge optionnelle, désactivée par défaut, et disponible seulement sur 2d (seul warehouse-2d-app a vss-alert-bridge/agent/vss-agent-ui comme dépendances ; 3d et mv3dt ne les ont pas). Si l'utilisateur est sur 3d/mv3dt et demande les Alerts, dites que c'est indisponible là au lieu d'essayer de l'activer. Sur 2d, demandez à l'utilisateur s'il le souhaite, et expliquez le compromis d'abord plutôt que de l'activer ou de le sauter pour lui : sans Alerts ils obtiennent le flux RT-CV de détection/suivi brut ; avec, les détections passent aussi par une étape d'analytique comportementale et une étape de vérification VLM (RT-VLM) avant qu'un incident soit surfacé, requêtable via l'agent/agent UI. Cette étape de vérification est la raison de l'activer — c'est ce qui empêche chaque détection brute de devenir un ticket. S'ils le veulent, notez que les quatre drapeaux doivent être définis ensemble (vss-alert-bridge.enabled, agent.enabled, vss-agent-ui.enabled, rtvi.vss-rtvi-vlm.enabled — remplacez le dernier par un vlmBaseUrl externe si n'utilisant pas le VLM dans le cluster) plus les valeurs endpoint Kafka/Elasticsearch/VST. Bloc complet : warehouse-2d-app/README.md §Alerts — mettez-le en couches pendant l'étape 6.
   • Nombre de streams. Demandez s'il n'est pas donné ; il dimensionne le plafond NUM_STREAMS à l'étape 5.

4. Demandez si l'installation personnalise bp-configurator.env (variables d'env supplémentaires, défauts différents) — ne supposez pas qu'aucune n'existe juste parce que l'utilisateur n'en a pas mentionné une. S'ils ne sont pas sûrs, demandez-leur de vérifier leur commande helm upgrade --install existante pour tout ce qui touche bp-configurator.env, fichier-basé ou inline. Énoncez le résultat en retour de toute façon :

   • Fichier de valeurs (-f my-values.yaml) → notez son chemin. Il est passé au script via -f à l'étape suivante et à helm lui-même à l'étape 7 — la sortie du script porte seulement bp-configurator.env, donc tout ce qui est d'autre dans ce fichier (storage class, ingress, drapeaux alerts) a toujours besoin que helm voit le fichier original directement. Voir references/streams.md.
   • Inline (--set/--set-json sur bp-configurator.env) → le script ne lit que des fichiers YAML, il ne peut pas consommer une chaîne --set. Déplacez-la dans un fichier de valeurs d'abord — voir references/streams.md pour la commande helm get values -a (secrets inclus, manipulez avec soin) et pourquoi elle ne peut pas être réduite. Ensuite traitez-la comme le cas de fichier de valeurs ci-dessus.
   • Pas de personnalisations — dites-le explicitement (par ex. « aucune surcharge bp-configurator.env personnalisée, donc rien de supplémentaire n'est nécessaire ici ») et procédez sans aucun de ce qui précède.

5. Exécutez le script stream-cap depuis la racine du repository :

   python3 deploy/helm/industry-profiles/warehouse-operations/scripts/compute_stream_cap.py \
     --mode <mode> --num-streams <N> -o values-stream-cap.generated.yaml

   • Si l'étape 4 a trouvé un fichier de valeurs de personnalisation, passez-le aussi ici via -f — autrement le fichier généré (construit à partir des défauts du chart, mis en couches en dernier) supprime silencieusement ces personnalisations. Voir references/streams.md.
   • Sans --hardware-profile, il exécute nvidia-smi sur l'index GPU 0 et mappe le nom à un HARDWARE_PROFILE en utilisant la même table que la référence warehouse de vss-deploy-profile. Si la détection échoue ou que le GPU n'est pas dans cette table, passez --hardware-profile explicitement. Les appareils edge IGX-THOR/DGX-SPARK ne sont pas supportés par ce chemin Helm.
   • Il affiche le nombre de streams effectif (possiblement plafonné) et la valeur syncFileCount pour rester synchronisé (voir references/streams.md pour pourquoi).
   • Il ne baisse jamais silencieusement la demande sans le dire — un plafond est toujours enregistré sur stderr.

6. Préparez le reste des valeurs — secrets, storage class, soit ingress/externalHost soit le fichier de valeurs NodePort selon le choix fait à l'étape 2, et — si les Alerts ont été activées à l'étape 3 — le bloc de valeurs Alerts à quatre drapeaux du README warehouse-2d-app §Alerts (endpoints Kafka/Elasticsearch/VST inclus). Sur mv3dt, ajoutez aussi --set rtvi.vss-rtvi-cv.standaloneWarehouse.mv3dt.fusion.maxExpectedSensors=<effective-streams> (même valeur que syncFileCount de l'étape 5). Si l'étape 4 a trouvé un fichier de valeurs de personnalisation, il va ici aussi (-f my-values.yaml) — le passer seulement au script à l'étape 5 couvre bp-configurator.env mais supprime tout le reste dans ce fichier de l'installation. Voir references/streams.md pour la commande helm upgrade --install complète avec le fichier généré mis en couches en dernier via -f.

7. Installez/mettez à jour, en chaînant le fichier généré après n'importe quel autre -f/--set override pour qu'il gagne sur bp-configurator.env. La commande de base est la même de toute façon ; seuls les overrides ingress-vs-NodePort diffèrent :

   helm dependency update deploy/helm/industry-profiles/warehouse-operations/warehouse-<mode>-app
   
   # Ingress:
   helm upgrade --install wh deploy/helm/industry-profiles/warehouse-operations/warehouse-<mode>-app \
     -n <namespace> --create-namespace \
     --set global.vssIngress.enabled=true \
     --set global.externalHost=<NODE_IP> \
     --set global.storageClass=<STORAGE_CLASS> \
     --set vios.vss-vios-nvstreamer.syncFileCount=<effective-streams> \
     ... \
     -f values-stream-cap.generated.yaml   # dernier : gagne sur bp-configurator.env
   
   # NodePort:
   helm upgrade --install wh deploy/helm/industry-profiles/warehouse-operations/warehouse-<mode>-app \
     -n <namespace> --create-namespace \
     -f deploy/helm/industry-profiles/warehouse-operations/warehouse-<mode>-app/values-nodeport.yaml \
     --set global.storageClass=<STORAGE_CLASS> \
     --set vios.vss-vios-nvstreamer.syncFileCount=<effective-streams> \
     -f values-stream-cap.generated.yaml   # dernier : gagne sur bp-configurator.env

   ... sont les overrides secrets/URL restants de l'étape 6 — voir references/streams.md.

   -f values-stream-cap.generated.yaml doit être le dernier -f dans la commande — c'est ce qui le fait gagner sur bp-configurator.env (plusieurs fichiers -f fusionnent dans l'ordre donné, le dernier gagne par clé de top-level). Cela inclut venir après values-nodeport.yaml dans le cas NodePort et après chaque autre -f dans les deux cas. --set ne suit pas cette règle : Helm applique toujours --set après chaque fichier -f indépendamment de la position en ligne de commande, donc un --set égaré sur bp-configurator.env ici remporterait toujours quoi qu'il en soit — l'étape 4 devrait déjà avoir converti tout tel override en un fichier de valeurs, pas l'avoir laissé inline.

8. Validation post-installation — confirmez que les pods se lèvent réellement avant de déclarer le succès ; voir warehouse-<mode>-app/README.md §Post-install validation, mais n'exécutez pas son kubectl get pods -w/port-forward verbatim — ceux-ci se bloquent éternellement. Utilisez kubectl wait --for=condition=Ready pod --all -n <namespace> --timeout=5m et un port-forward en arrière-plan à la place.

9. Réexécutez le script chaque fois que NUM_STREAMS ou le GPU cible change — le fichier de valeurs-override n'est pas suivi automatiquement ; régénérez et helm upgrade après un changement matériel.

Prérequis

• Cluster Kubernetes accessible via kubectl, tous les nœuds Ready.
• NVIDIA GPU Operator installé, pour que les nœuds rapportent nvidia.com/gpu comme allocatable.
• StorageClass présent pour les PVCs VST/Elasticsearch (global.storageClass).
• Helm 3.x et kubectl.
• Clé API NGC pour le secret d'extraction d'images et le job de téléchargement de modèles/données d'application.
• Contrôleur ingress installé si utilisant ingress (voir la section « No ingress controller: NodePort » du README du chart pour l'alternative).
• Serveur TURN pour la lecture WebRTC hors-cluster (global.turnServerUrl).

Détail complet, valeurs, et commandes exactes : voir deploy/helm/industry-profiles/warehouse-operations/warehouse-<mode>-app/README.md §Prérequis (identique entre 2d/3d/mv3dt). Cette skill ajoute seulement l'étape stream-cap ; elle ne remplace pas la configuration du chart — le précheck à l'étape 1 est une passe de santé rapide, pas un substitut à la lecture de cette section au premier déploiement.