vss-deploy-warehouse-helm

# VSS Warehouse — Helm Deploy Do not use this skill for: - Docker Compose warehouse deployment — use `vss-build-vision-ai`'s [`references/warehouse.md`](../../vss-build-vision-ai/references/profiles/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`](../../../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: ```bash 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`](references/streams.md#if-your-install-customizes-bp-configuratorenv). - **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`](references/streams.md#if-your-install-customizes-bp-configuratorenv) 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: ```bash 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`](references/streams.md#if-your-install-customizes-bp-configuratorenv). - 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](../../vss-build-vision-ai/references/sizing.md). 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`](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`](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: ```bash 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`](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.