VSS Configurator
The VSS Configurator is a unified configuration management service that provides two main components:
Profile Configuration Manager
Overview
The Profile Configuration Manager automatically adjusts application settings based on hardware profiles (GPU type) and deployment modes (2D/3D).
To enable the Profile Configuration Manager, you must set:
By default, the Profile Configurator is disabled (ENABLE_PROFILE_CONFIGURATOR=false).
When enabled, it runs before the API server starts and adjusts configuration files based on your GPU hardware profile.
Architecture:
Key Features:
- Detects your GPU type (H100, GB300, L40S, RTXPRO6000BW, RTXPRO6000BW-SE, RTXPRO4500BW, IGX-THOR, DGX-SPARK).
- Adjusts settings based on 2D or 3D deployment mode
- Updates YAML, JSON, and text configuration files
- Validates that your environment is configured correctly
When you need it:
- Deploying to different GPU hardware
- Switching between 2D and 3D modes
- Ensuring configurations match hardware capabilities
Execution Flow:
- Load Environment Variables - Read
HARDWARE_PROFILE,MODE, etc. - Select Profile - Use the requested hardware profile if provided; unknown profile names are preserved and can still use
commonsconfiguration - Validate Environment - Check env vars have valid values
- Execute Prerequisites - Run pre-processing operations (e.g., count files)
- Compute Variables - Calculate
final_stream_count, timeouts, etc. - Execute File Operations - Update YAML, JSON, text files
Quick Start
Minimal working example - Copy this and modify for your GPU:
What happens:
- User sets
HARDWARE_PROFILE=GB300,MODE=3d, andNUM_STREAMS=80 - Configurator looks up GB300’s 3D limit:
max_streams_supported=71 - Computes:
final_stream_count = min(80, 71) = 71 - Updates
config.yamlwithnum_sensors: 71
That’s it! The GB300 GPU won’t be overloaded because the system automatically capped the streams.
Core Concepts
Two-Part Structure: Commons + Profiles
How they work together:
The same formula produces different results based on each GPU’s capabilities.
Deployment Modes
The warehouse configuration has separate rules for each deployment mode:
Example: The shipped GB300 profile supports 161 streams in 2D mode but 71 in 3D mode.
Inheritance Model
By default, Hardware profiles inherit from commons and can add their own rules:
Key point: Profile-specific settings are APPENDED to commons, not replaced (unless you explicitly disable inheritance).
commons is shared metadata and shared behavior. It is not a selectable hardware profile.
If HARDWARE_PROFILE is not present in the profile configuration file, the Configurator preserves the requested hardware profile name and runs with common configuration only. This is useful for deployments where the shared commons sections are enough for the selected mode. Commons-only operation works only when all referenced values can resolve without profile-specific variables, or when the configuration provides a fallback variable such as effective_max_streams_supported.
Required Environment Variables
The following environment variables must be set to use the Profile Configuration Manager:
Optional Environment Variables
Mode-less profile YAML
When DEPLOYMENT_MODES_ENABLED=false, omit nested 2d / 3d keys. Commons lists can sit directly under commons or under commons.default. Hardware settings sit directly under the profile name:
MODE is ignored in this layout. Warehouse blueprints keep DEPLOYMENT_MODES_ENABLED=true.
Configuration Reference
Config File Schema
Full Schema
The blueprint_config.yml file has this structure:
Field Reference
max_streams_supported
Type: Integer Required: Yes (for each deployment mode) Purpose: Maximum concurrent streams this GPU can handle
This value becomes available as ${max_streams_supported} in variable expressions.
To add a new hardware profile (e.g. a new GPU), add a profile block with max_streams_supported for each mode; the profile automatically inherits all commons rules unless use_commons is set to false.
Refer to RT-DETR Real-Time Performance for 2D profile, 2D profile with Agents, and Sparse4D Real-Time Performance for 3D profile for more details on the max streams supported for a particular GPU. If GPU is not found in list, then increase the streams gradually to find the optimal number of streams that can be used.
Hardware Profiles Reference
The following hardware profiles are defined in blueprint_config.yml. Names and max_streams_supported values must match the config file.
use_commons
Type: Object
Required: No (defaults to true for all)
Purpose: Control inheritance from commons section
Values:
true(default): Use commons for current mode (2d or 3d)false: Don’t use commons, only profile-specific"2d"or"3d": Use commons from specified mode regardless of current mode
variables
Type: List of key-value dictionaries Required: No Purpose: Define computed values
Variables are evaluated top-to-bottom, so later ones can reference earlier ones.
file_operations
Type: List of operation objects Required: No Purpose: Define config file modifications
See Operation Types Reference for details.
prerequisites
Type: List of operation objects Required: No Purpose: Operations that run BEFORE variable processing
Prerequisites are useful when you need to dynamically generate variables based on file system state. For example, counting video files before deciding stream limits.
Execution order: Validation -> Prerequisites -> Variables -> File Operations
Operation Types Reference
Choose the operation type by file format:
Common Options (All Operations)
All file operations support these options:
backup - Automatic file backup
Type: Boolean
Default: true
Purpose: Create a timestamped backup before modifying the file
Backup filename format: {original_name}.backup_{YYYYMMDD_HHMMSS}{extension}
enabled - Skip an operation without removing it from the YAML
Type: Boolean or ${VAR} after substitution
Default: true (key omitted means enabled)
Purpose: Run or skip a prerequisite or file operation. Warehouse keep_count uses enabled: false to leave sample videos in place. Values are substituted from computed variables, so enabled: "${trim_sample_videos}" works when that variable evaluates to true or false.
1. yaml_update
Updates values in YAML files while preserving structure.
Before:
After:
2. text_config_update
Updates key-value pairs in text files (.txt, .conf, .cfg).
Supported formats: key=value, key: value, key value
3. json_update
Updates values in JSON files with nested object support.
Before:
After:
Writes preserve the original indent style and whether the file ended with a newline.
array_kv_updates - Patch objects inside a JSON array by matching a field (dot notation in updates cannot target array elements). Used in warehouse configs to set Kafka vs Redis sourceType / sinkType on app[] entries.
You can combine updates (dot-notation keys) and array_kv_updates on the same json_update operation.
When a computed variable evaluates to a Python list or None, json_update writes a JSON array or null (for example kafka.brokers). See Typed list and null values.
4. text_replace
Ordered text edits on any file. Use when structured YAML/JSON parsers are too rigid (shell scripts, compose fragments, mixed text).
Environment variables in pattern, replacement, and lines are substituted before the edit runs.
5. file_management
Manages files in directories. Supports two actions: keep_count and file_count.
Action: keep_count - Keep only N files, remove the rest
Use case: If you can only process 4 streams, keep only 4 sample video files:
- Before: 10 video files
- After (count=4): 4 video files (first 4 alphabetically kept, rest removed)
When keep_count removes video files, each removed filename without its extension is treated as a sensor ID. If CALIBRATION_DIR_MOUNT_PATH and CALIBRATION_FILE_NAME point to calibration.json, matching sensors are removed from sensors, ROI sensors lists are filtered, and ROIs with no remaining sensors are dropped. After stream-count changes, verify the filtered calibration.json before relying on downstream calibration, ROI, or BEV behavior.
Action: file_count - Count files and store result in a variable
Use case: Dynamically determine how many video files are available, then use that count in variable calculations.
Parameters:
Note: file_count is typically used in the prerequisites section so the count is available for variable calculations
Variable System Reference
Declaration Syntax
Variables are declared as a list of single-key dictionaries:
Evaluation order: Top to bottom. Later variables can reference earlier ones.
Environment Variable Substitution
Use ${VAR_NAME} to reference environment variables:
Supported Functions
Supported Operators
Conditional Expressions (If-Else)
Python-style ternary expressions:
Syntax: value_if_true if condition else value_if_false
Comparison operators: >, <, >=, <=, ==, !=
Logical operators: and, or, not
Examples:
Typed list and null values
Most computed variables are stored as strings. If an expression evaluates to a list or None, the Configurator keeps that typed value and json_update can write a JSON array or null.
Use a single ${VAR} as the entire update value so the typed object is applied. Concatenating a typed variable into a larger string falls back to string substitution.
Validation Reference
Basic Validation
allowed_values - Exact match against a list:
allowed_patterns - Wildcard match (* = any characters, ? = single character):
disallowed_values - Block specific values:
disallowed_patterns - Block values matching patterns:
regex - Regular expression match:
Validation Options
required - Skip validation if variable is not set:
error_message - Custom error message:
Conditional Validation
Apply validation only when a condition is met:
Condition operators:
Advanced Validation
Compound conditions (AND/OR):
Trigger-based validation (when_equals + validate_conditions):
Use this to validate OTHER variables when THIS variable has a specific value:
Logic:
- IF
SAMPLE_VIDEO_DATASET="nv-warehouse-4cams"→ check the conditions - IF
SAMPLE_VIDEO_DATASETis anything else → skip this validation
Comparison: condition vs when_equals:
Examples & Best Practices
Complete Examples
Example 1: Minimal Profile (Most Common)
Just specify stream limits; inherit everything else:
“I’m an H100. I can handle 61 streams in 2D and 19 in 3D. Use all standard rules from commons.”
Example 2: Profile with Extra Operations
Inherit commons but add GPU-specific operations:
“I’m an IGX-THOR. Use commons rules, BUT add extra config changes for 2D (DeepStream/VPI) and 3D (timeouts, VST overlay).”
Execution order:
- Commons file operations run first
- IGX-THOR specific operations run after
Example 3: Profile with Custom Variables
Add calculated variables for a less powerful GPU:
“I’m a CUSTOM_GPU (slower GPU). I need 2× longer timeouts.”
Example 4: Complete Override
Completely custom behavior, ignoring commons:
“I’m experimental hardware. Ignore all commons; I define everything myself.”
Example 5: Using Prerequisites and File Count
Dynamic configuration based on available files:
“Count available videos first, then limit streams to the minimum of: user request, available videos, and GPU capacity.”
Example 6: Full Configuration File
A complete blueprint_config.yml showing all features:
Adding a New Hardware Profile
You do not always need to add a profile for hardware that is not in the predefined list (H100, GB300, L40S, etc.). If the shared commons configuration can resolve all variables for the selected mode, the Configurator preserves the requested HARDWARE_PROFILE value and applies commons-only configuration.
Add a profile in blueprint_config.yml when the hardware needs profile-specific values, such as stream limits, timeouts, or file updates. Commons-only custom hardware also needs either no profile-specific variable references, or fallback variables such as effective_max_streams_supported. If commons validation restricts HARDWARE_PROFILE to an allowed list, update that validation before using a new custom value.
Steps:
-
Add a profile block only if needed in
blueprint_config.ymlunder the hardware profiles section. Use a clear, unique name (e.g.MY-GPU,CUSTOM-EDGE) that you will set inHARDWARE_PROFILE. -
Define stream limits for each mode. At minimum, set
max_streams_supportedfor2dand3d. The configurator will inherit all commons rules (variables, file_operations, validation) unless you override them. -
Optional: Add profile-specific
variablesorfile_operationsif this hardware needs different timeouts, config keys, or file updates than the commons. -
Optional: If the new profile name must be accepted by validation, add it to the
HARDWARE_PROFILEallowed_valuesin thecommons.variable_validationsection for both2dand3d.
Minimal new hardware (stream limits only):
Then set HARDWARE_PROFILE=MY-GPU when deploying. Commons will apply; stream count will be capped to 6 (2D) or 4 (3D).
New hardware with custom config updates:
Here the profile inherits commons and adds longer timeouts and extra file updates for 3D mode. Ensure CUSTOM-EDGE is added to allowed_values for HARDWARE_PROFILE in commons.variable_validation if you use validation.
Best Practices
-
Use Commons for Shared Logic
Put common calculations and operations in the commons section. Most profiles should only specify
max_streams_supported. -
Keep Profiles Simple
A minimal profile is better:
-
Use Variables for Computed Values
Don’t hardcode values that depend on hardware:
-
Validate Early
Use variable validation to catch errors before they cause runtime failures.
-
Use Meaningful Names
Choose descriptive variable names:
-
Keep Conditionals Simple
Prefer simple conditions over deeply nested ternaries:
-
Document Custom Configurations
Add comments explaining why profile-specific overrides are needed:
-
Test All Modes
Ensure your config works for both 2d and 3d modes on each hardware profile.
Troubleshooting
Common Errors
“Variable not found” or empty value
Causes:
- Variable name typo
- Variable defined after it’s used (evaluation order matters)
- Variable defined in different mode section
Fix: Check spelling and ensure variables are defined before use:
“Validation failed”
Cause: Environment variable has invalid value.
Fix: Check your environment variable:
“File not found” or “Permission denied”
Causes:
- Path doesn’t exist
- Environment variable in path is not set
- Permission issues
Fix: Verify the path and environment variables:
“Hardware profile not found, using common configurations only”
Cause: HARDWARE_PROFILE does not match a top-level hardware profile in the profile configuration file.
Fix: If commons-only behavior is intended, make sure all commons variables and file operations can resolve without profile-specific values, or provide fallbacks such as effective_max_streams_supported. If the hardware needs profile-specific limits or file updates, add a profile block and update any HARDWARE_PROFILE validation rules that restrict allowed values.
“Variable from file_count not available”
Cause: The file_count operation is in file_operations instead of prerequisites.
Fix: Move file_count to prerequisites so it runs before variable processing:
“Backup file not created”
Causes:
backup: falseis explicitly set- Permission issues in the target directory
- Target file doesn’t exist (nothing to backup)
Fix: Check your operation has backup: true (or omit it, since true is the default):
Debugging Tips
-
Check environment variables first:
-
Use simple profiles to isolate issues:
-
Check variable evaluation order:
Variables are processed top-to-bottom. A variable can only reference variables defined above it.
-
Verify file paths exist:
Before running the configurator, check that target files exist at the expected paths.
-
Review the execution flow:
Remember: Validation → Prerequisites → Variables → File Operations
- If validation fails, prerequisites, variables, and file operations will not run
- If prerequisites fail, variables and file operations will not run
- Variables from
file_countare only available if defined inprerequisites
Sensor Configuration Manager
Overview
The Sensor Configuration Manager handles camera/sensor configurations for blueprint deployments. It runs as a background service alongside the Profile Configurator.
What it does:
- Fetches sensor information from various sources (Sensor Bridge, NVStreamer, or file)
- Fetches calibration data from various sources (API, upload, or file mount)
- Creates sensor mappings with RTSP URLs, groups, and regions
- Registers sensors with VMS
- Publishes sensor configuration events to message brokers (Kafka/Redis)
Architecture:
Core Concepts
Sensor Information Sources
The manager can fetch sensor information from these sources:
Calibration Modes
Calibration data contains camera parameters (intrinsic/extrinsic) needed for warehouse blueprint.
Sensor Mapping
The sensor mapping connects:
- Sensor ID/Name - Unique identifier for the camera
- RTSP URL - Stream URL for the camera
- Group ID - Logical grouping of cameras
- Region - Physical location/area
Example mapping:
Configuration Reference
This section provides a comprehensive reference for all environment variables used by the Sensor Configuration Manager.
This reference lists environment variables read by the VSS Configurator service source code. Deployment and profile-config variables such as BP_PROFILE, STREAM_TYPE, COMPOSE_PROFILES, VSS_APPS_DIR, and VSS_DATA_DIR are inputs to the warehouse deployment and profile configuration files. They are documented in the Warehouse Quickstart and profile examples, and are not Sensor Configuration Manager runtime knobs unless a profile configuration file references them.
General Settings
Calibration Settings
Uploading Calibration Data (upload mode):
Mount Mode Volume Example:
Sensor Source Settings
Sensor File Format (for file mode):
Required fields: camera_name, rtsp_url
Optional fields: group_id, region (can also be obtained from calibration data)
When SENSOR_INFO_SOURCE=file, the RTSP URLs provided in the sensor info source file must be accessible from the machine where VSS is deployed. If the RTSP streams originate from remote machines, ensure those streams are discoverable by VIOS.
NVStreamer Settings
The defaults in this table are the Sensor Configuration Manager’s standalone
application fallbacks. The shipped VSS Compose deployment overrides both
endpoint variables with
http://${NVSTREAMER_IP}:${NVSTREAMER_HTTP_PORT}/api/v1/sensor/...; the
NVStreamer service defaults NVSTREAMER_HTTP_PORT to 31000.
VMS Integration Settings
Sensor Registration Details:
Each sensor is registered with the VMS containing:
- Sensor name: Unique identifier for the camera
- RTSP URL: Stream URL for the camera
- Tags: Combined region and group_id in format
region|group_id
The add call retries until success. A client timeout or HTTP 499 can occur while VST is still processing a slow add; the next retry may then see HTTP 400 with Sensor exists already for the same RTSP URL, which the Configurator treats as success. A same-name / different-URL collision (User given name is invalid or already exists) is a real conflict and continues to retry.
Message Broker Settings
Common Settings:
Kafka Settings:
Redis Settings:
Redis Duplicator Settings:
How Redis Duplicator Works:
- Reads events from the source stream (e.g.,
vst.event) - For CV target topic: appends
CV_SUFFIXto camera names (e.g.,camera-01→camera-01-cv) - For PN26 target topic: appends
PN_SUFFIXto camera names (or uses original if empty) - Publishes modified events to both target streams simultaneously
Naming/Suffix Settings
Config Message Metadata Settings
Video Upload Settings
NVSTREAMER_UPLOAD_BASE_URL is not overridden by the shipped Configurator
Compose file. When you enable ENABLE_NVSTREAMER_VIDEO_UPLOAD, set it
explicitly to an NVStreamer address reachable from the Configurator container;
do not rely on the standalone fallback for a Compose deployment.
Examples
Example 1: Upload Mode with Redis
Gets sensor/RTSP URLs from the Metropolis Sensor Bridge (MSB) and accepts calibration via POST to /calibration (upload mode).
Publishes sensor configuration events to Redis; use when you have an external sensor bridge and want to upload calibration manually.
Example 2: NVStreamer Source with VMS
The Profile Configuration Manager optionally recomputes BEV groups before
sensor discovery for 3D and MV3DT deployments in mount mode. The Sensor
Configuration Manager then reads the stream list from NVStreamer, builds the
sensor mapping from calibration, registers each sensor with VMS, and sends the
configuration to SDR. This matches warehouse blueprint deployments such as
bp-configurator-2d, bp-configurator-3d, and bp-configurator-mv3dt.
Example 3: File-based Sensors
Uses a static sensor list from a JSON file at SENSOR_FILE_PATH and calibration from a mounted volume (mount mode).
Publishes sensor configuration events to Kafka; for environments where sensor metadata is file-driven rather than from MSB or NVStreamer.
Example 4: Docker Compose (Complete)
Runs the full VSS Configurator: profile configurator (GPU/mode), NVStreamer as sensor source, calibration from a mount, VMS registration, and Kafka for sensor events. Single compose file with all integration points (profile config, sensor mapping, SDR, VST add API, message broker) for a complete deployment.
Troubleshooting
Sensor Manager Issues
“Calibration file not found”
Causes:
- Calibration file doesn’t exist at the specified path
- Volume mount is incorrect
- API endpoint is unreachable (fetch mode)
Fix:
“Sensor mapping not created yet”
Cause: Calibration data hasn’t been received/processed yet.
Fix: Wait for calibration to be fetched, or upload it manually:
“Sensor not found in calibration file”
Cause: Sensor exists in MSB/NVStreamer but not in calibration data.
Fix: Ensure the calibration file and the selected sensor source use the same sensor IDs. Check sensor mapping logs for any skipped sensors or calibration mismatches.
“Error connecting to Kafka/Redis”
Causes:
- Kafka/Redis server is not running
- Incorrect host/port configuration
- Network connectivity issues
Fix:
API Reference
The VSS Configurator exposes the following REST API endpoints:
Calibration Endpoints
POST /calibration
Upload calibration data (upload mode) or receive warning (fetch mode).
Request:
Response (Upload Mode - Success):
Response (Fetch Mode - Warning):
Status Codes:
200 OK- Success or warning400 Bad Request- Invalid calibration data503 Service Unavailable- Calibration process disabled
GET /download
Download the current calibration file.
Request:
Response: Binary file download (calibration.json)
Status Codes:
200 OK- File downloaded404 Not Found- No calibration file available500 Internal Server Error- Error sending file503 Service Unavailable- Calibration process disabled
Sensor Endpoints
GET /cameras
Get list of all configured sensor/camera information.
Request:
Response:
Status Codes:
200 OK- Success503 Service Unavailable- Sensor mapping not created yet500 Internal Server Error- Error retrieving sensor list
GET /groups
Get list of all sensor group names.
Request:
Response:
Status Codes:
200 OK- Success503 Service Unavailable- Sensor mapping not created yet or calibration disabled500 Internal Server Error- Error retrieving group list
Health Endpoints
GET /healthz
Liveness probe - checks if the service is running.
Request:
Response:
Status Codes:
200 OK- Service is healthy
GET /readyz
Readiness probe - checks the profile-config readiness marker state.
Request:
Response (Ready):
Response (Not Ready):
Status Codes:
200 OK- Profile-config readiness marker exists, or profile configuration is disabled503 Service Unavailable- Profile-config readiness marker is missing while profile configuration is enabled
Note: If ENABLE_PROFILE_CONFIGURATOR=false, this endpoint always returns ready.
Scope: /readyz only reflects whether the profile-config marker file exists when profile configuration is enabled. It does not prove calibration processing, sensor mapping, SDR/message broker publish, VMS sensor registration, BEV center recompute, Redis duplication, or video upload completion. Use logs, /cameras, broker or VMS checks, and /video-upload-status as appropriate for those workflows.
GET /video-upload-status
Reports the current NVStreamer and/or VMS video upload state. This endpoint is useful for callers that need to wait until configured videos are uploaded before continuing.
Request:
Response (Completed):
Response (Pending):
Response (Failed):
Response (Disabled):
Status Values:
completed- Upload finished;readyis truefailed- Upload failed; response includeserrorin_progress- Upload is currently runningnot_started- Upload is enabled but has not started yetdisabled- Both video upload features are disabled
Response Fields:
status- One ofcompleted,failed,in_progress,not_started, ordisabledmessage- Human-readable status detailuploaded_count- Number of videos uploaded so farready- True only when upload status iscompletederror- Optional error detail for failed uploads
Status Codes:
200 OK- Video upload completed503 Service Unavailable- Video upload is pending, in progress, or failed404 Not Found- Video upload is disabled
API Usage Examples
Check Service Health
Upload and Verify Calibration
Kubernetes Probes Configuration
Sample Use Case
For an example of how the VSS Configurator is used in the Warehouse Operations Blueprint, see VSS Configurator for the Warehouse Blueprint. The guide covers profile and sensor configuration flow, configuration inputs, file changes, and hardware-specific overrides.