vss-deploy-warehouse-helm

name	vss-deploy-warehouse-helm
description	Use when the user asks to deploy, upgrade, or size the VSS warehouse blueprint (2D / 3D / MV3DT) on Kubernetes via Helm — as opposed to Docker Compose, which is covered by vss-build-vision-ai's warehouse reference. Handles GPU-aware NUM_STREAMS capping so the deployment matches what the perception pipeline can actually sustain.
license	Apache-2.0
metadata	{"version":"1.0.0","author":"NVIDIA Video Search and Summarization team","github-url":"https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization","tags":"nvidia blueprint deployment helm kubernetes warehouse"}

VSS Warehouse — Helm Deploy

Do not use this skill for:

• Docker Compose warehouse deployment — use vss-build-vision-ai's references/warehouse.md; it owns the HARDWARE_PROFILE → GPU mapping table and the blueprint_config.yml stream-cap semantics this skill reuses.
• Non-warehouse Helm profiles (base, search, lvs, alerts) — those don't have a bp-configurator GPU-aware stream cap; deploy them per their own chart READMEs.
• Runtime operations (adding cameras, querying behavior analytics) — use vss-manage-alerts / vss-query-analytics against the running deployment.

Why this exists

Docker Compose's warehouse deploy caps NUM_STREAMS per GPU automatically: the configurator reads deploy/docker/industry-profiles/warehouse-operations/blueprint-configurator/blueprint_config.yml's max_streams_supported table for the detected HARDWARE_PROFILE and mode, and clamps final_stream_count = min(NUM_STREAMS, max_streams_supported).

The Helm charts (deploy/helm/industry-profiles/warehouse-operations/warehouse-{2d,3d,mv3dt}-app) do not do this — their bp-configurator.env ships a fixed NUM_STREAMS and never sets HARDWARE_PROFILE at all (ENABLE_PROFILE_CONFIGURATOR=false). A user who asks for more streams than the GPU can sustain gets no protection. This skill closes that gap by computing the same cap Compose would apply and writing it into a Helm values-override file before install.

Available Scripts

Script	Purpose	Arguments
../../../deploy/helm/industry-profiles/warehouse-operations/scripts/compute_stream_cap.py	Detect GPU (or take an explicit HARDWARE_PROFILE), read max_streams_supported from blueprint_config.yml, cap the requested stream count, and write a bp-configurator.env-patched values-override YAML. Pass any values file(s) your install already uses via -f so custom bp-configurator.env entries in them aren't dropped.	--mode {2d,3d,mv3dt} --num-streams N [--hardware-profile P] [--gpu-index I] [-f VALUES]... [-o FILE]

This script has no skill/agent dependency — a user who doesn't want to use this skill can run it directly (python3 compute_stream_cap.py --mode 2d --num-streams 8) and pass the generated file to helm upgrade/install -f themselves.

Instructions

1. Precheck the cluster and required inputs before touching Helm — don't assume a fresh cluster already has these. Run each check and report pass/fail back to the user:

   kubectl cluster-info                         # cluster reachable
   kubectl get nodes                             # all nodes Ready
   kubectl get storageclass                      # a StorageClass exists
   kubectl get nodes -o jsonpath='{.items[*].status.allocatable.nvidia\.com/gpu}{"\n"}'
                                                  # non-empty -> GPU Operator has registered GPUs
   helm version --short                           # Helm 3.x
   

   Also ask whether the user already has an NGC API key — that can't be checked from cluster state, only asked about.

   On any failure, don't just link the user to the README and stop — hand them the actual fix, copied from the chart README, and offer to run it for them:

   • No StorageClass → relay the local-path-provisioner install + kubectl patch storageclass snippet from warehouse-<mode>-app/README.md §Prerequisites (bare-metal option) — or ask what StorageClass they intend to use if they already have one in mind. Multi-node cluster: local-path's node affinity can strand vss-vios-nvstreamer's PVCs across different nodes (didn't match PersistentVolume's node affinity) — relay the same section's nfs-subdir-external-provisioner snippet instead, and set vios.vstStorage.vstData, .vstVideo, and .streamerVideos .storageClass to nfs-client via three separate --set flags (or just global.storageClass) rather than local-path.
   • No nvidia.com/gpu allocatable → relay the NVIDIA GPU Operator install steps from §Prerequisites (links to the GPU Operator getting-started guide) and the recommended driver versions listed there.
   • Cluster unreachable / nodes not Ready → this one the user has to fix outside Helm/this skill entirely; say so plainly rather than suggesting a chart-level fix.
   • No NGC API key → point at §Required secrets in the chart README for how to create the pull secret, don't just say "get an NGC API key."

   Only proceed to step 2 once cluster/StorageClass/GPU-Operator/Helm all pass and the user has confirmed they have an NGC API key — an install started before that will fail partway through in a way that's harder to debug than catching it here.

2. Ask ingress vs. NodePort — this determines both what's installed in this step and which install command gets used in step 6, so resolve it before going further, don't default silently to one or the other:

   • Ingress (needed off-cluster / for a stable hostname) → check whether an ingress controller is already installed (kubectl get ingressclass). If not, relay the haproxy-ingress install snippet from warehouse-<mode>-app/README.md §"Install the ingress controller" and offer to run it. Note this is a one-time, per-cluster step, not per-app.
   • NodePort (simplest for a quick local/single-node deploy, no ingress controller needed) → tell the user the chart ships values-nodeport.yaml for this — the install command in step 6 changes to -f values-nodeport.yaml layered under the stream-cap file, and the service URLs move to <NODE_IP>:<port> instead of <NODE_IP>/<path>. See §"No ingress controller: NodePort" and §URLs in the chart README for the exact ports. If the user hasn't said which they want and there's no clear signal (e.g. "just get it running locally" implies NodePort; "expose it for the team" implies Ingress), ask rather than guessing.

3. Determine mode and whether to enable Alerts:

   • Mode. Use 2d, 3d, or mv3dt if the request already names one. Otherwise ask — don't guess:
     • 2d — 2D object detection & tracking.
     • 3d — standalone RTVI-CV-3D / multi-camera 3D tracking on calibrated inputs.
     • mv3dt — Multi-View 3D Tracking warehouse profile. Also needs rtvi.vss-rtvi-cv.standaloneWarehouse.mv3dt.fusion.maxExpectedSensors set to the effective stream count in step 6/7 (default 4) — it's BEV fusion's own camera-count setting, separate from NUM_STREAMS/syncFileCount, and the stream-cap script doesn't touch it.
   • Alerts. Not a fourth mode — an optional overlay, off by default, and only available on 2d (warehouse-2d-app is the only chart with vss-alert-bridge/agent/vss-agent-ui as dependencies; 3d and mv3dt don't have them). If the user is on 3d/mv3dt and asks for Alerts, say it's not available there instead of trying to enable it. On 2d, ask the user whether they want it, and explain the tradeoff first rather than enabling or skipping it for them: without Alerts they get the raw RT-CV detection/tracking stream; with it, detections also pass through a behavior-analytics stage and a VLM verification step (RT-VLM) before anything is surfaced as an incident, queryable through the agent/agent UI. That verification step is the reason to turn it on — it's what keeps every raw detection from becoming a ticket. If they want it, note the four flags have to be set together (vss-alert-bridge.enabled, agent.enabled, vss-agent-ui.enabled, rtvi.vss-rtvi-vlm.enabled — swap the last for an external vlmBaseUrl if not using the in-cluster VLM) plus Kafka/Elasticsearch/VST endpoint values. Full block: warehouse-2d-app/README.md §Alerts — layer it in during step 6.
   • Stream count. Ask if not given; it sizes the NUM_STREAMS cap in step 5.

4. Ask whether the install customizes bp-configurator.env (extra env vars, different defaults) — don't assume none exist just because the user didn't mention one. If they're unsure, ask them to check their existing helm upgrade --install command for anything touching bp-configurator.env, file-based or inline. State the outcome back to them either way:

   • Values file (-f my-values.yaml) → note its path. It gets passed to the script via -f in the next step and to helm itself in step 7 — the script's output only carries bp-configurator.env, so anything else in that file (storage class, ingress, alerts flags) still needs helm to see the original file directly. See references/streams.md.
   • Inline (--set/--set-json on bp-configurator.env) → the script only reads YAML files, it can't consume a --set string. Move it into a values file first — see references/streams.md for the helm get values -a command (secrets included, handle with care) and why it can't be trimmed. Then treat it as the values-file case above.
   • No customizations → say so explicitly (e.g. "no custom bp-configurator.env overrides, so nothing extra is needed here") and proceed without any of the above.

5. Run the stream-cap script from the repo root:

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

   • If step 4 found a customizing values file, pass it here too via -f — otherwise the generated file (built from chart defaults, layered last) silently drops those customizations. See references/streams.md.
   • Without --hardware-profile, it runs nvidia-smi on GPU index 0 and maps the name to a HARDWARE_PROFILE using the same table as vss-build-vision-ai's warehouse reference. If detection fails or the GPU isn't in that table, pass --hardware-profile explicitly. IGX-THOR/ DGX-SPARK edge devices aren't supported by this Helm path.
   • No local nvidia-smi (running helm/kubectl from a bastion, laptop, or CI runner rather than a GPU node): kubectl exec into a GPU Operator daemonset pod (driver or device-plugin, e.g. kubectl get pods --all-namespaces -l app=nvidia-driver-daemonset) and run nvidia-smi --query-gpu=name --format=csv,noheader there instead, then map the name and pass --hardware-profile.
   • It prints the effective (possibly capped) stream count and the syncFileCount value to keep in step (see references/streams.md for why).
   • It never lowers the request silently without saying so — a cap is always logged to stderr.

6. Prepare the rest of the values — secrets, storage class, either ingress/externalHost or the NodePort values file per the choice made in step 2, and — if Alerts was enabled in step 3 — the four-flag Alerts values block from warehouse-2d-app/README.md §Alerts (Kafka/ Elasticsearch/VST endpoints included). On mv3dt, also add --set rtvi.vss-rtvi-cv.standaloneWarehouse.mv3dt.fusion.maxExpectedSensors=<effective-streams> (same value as syncFileCount from step 5). If step 4 found a customizing values file, it goes here too (-f my-values.yaml) — passing it only to the script in step 5 covers bp-configurator.env but drops everything else in that file from the install. See references/streams.md for the full helm upgrade --install command with the generated file layered in last via -f.

7. Install/upgrade, chaining the generated file after any other -f/--set overrides so it wins on bp-configurator.env. The base command is the same either way; only the ingress-vs-NodePort overrides differ:

   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> \
     --set vios.vss-vios-nvstreamer.rtsp.instanceCount=<effective-streams> \
     ... \
     -f values-stream-cap.generated.yaml   # last: wins on 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> \
     --set vios.vss-vios-nvstreamer.rtsp.instanceCount=<effective-streams> \
     -f values-stream-cap.generated.yaml   # last: wins on bp-configurator.env
   

   ... is the remaining secrets/URL overrides from step 6 — see references/streams.md.

   -f values-stream-cap.generated.yaml has to be the last -f in the command — that's what makes it win on bp-configurator.env (multiple -f files merge in order given, later wins per top-level key). That includes coming after values-nodeport.yaml in the NodePort case and after every other -f in both. --set doesn't follow this rule: Helm always applies --set after every -f file regardless of command-line position, so a stray --set on bp-configurator.env here would still win no matter where you put it — step 4 should already have converted any such override into a values file, not left it inline.

8. Post-install validation — confirm pods actually come up before declaring success; see warehouse-<mode>-app/README.md §Post-install validation, but don't run its kubectl get pods -w/port-forward verbatim — those block forever. Use kubectl wait --for=condition=Ready pod --all -n <namespace> --timeout=5m and a backgrounded port-forward instead.

9. Re-run the script whenever NUM_STREAMS or the target GPU changes — the values-override file isn't tracked automatically; re-generate and re-helm upgrade after a hardware change.

Prerequisites

• Kubernetes cluster reachable via kubectl, all nodes Ready.
• NVIDIA GPU Operator installed, so nodes report nvidia.com/gpu as allocatable.
• StorageClass present for VST/Elasticsearch PVCs (global.storageClass).
• Helm 3.x and kubectl.
• NGC API key for the image pull secret and model/app-data download job.
• Ingress controller installed if using ingress (see the chart README's "No ingress controller: NodePort" section for the alternative).
• TURN server for WebRTC playback off-cluster (global.turnServerUrl).

Full detail, values, and exact commands: see deploy/helm/industry-profiles/warehouse-operations/warehouse-<mode>-app/README.md §Prerequisites (identical across 2d/3d/mv3dt). This skill only adds the stream-cap step; it doesn't replace chart setup — the precheck in step 1 is a fast sanity pass, not a substitute for reading that section on first deploy.