Getting Started
Holoscan for Media
Platform setup, cluster prerequisites, reference applications, deployment, verification, monitoring, application development, troubleshooting, and support for Holoscan for Media are covered in the NVIDIA Holoscan for Media user guide.
Prerequisites
Before proceeding, check the Support Matrix to verify that the required hardware and software are available.
OpenShift Setup
Complete the following steps before deployment.
1. Create Namespace
On OpenShift you can use oc new-project <namespace> instead; the command creates the namespace and can set additional project defaults (for example, display name). The remaining steps, including SCC binding, apply the same either way.
2. Grant SCC Permission
Grant the required OpenShift SCC permission to the service account that runs your pods. Many deployments use the namespace default account when spec.serviceAccountName is unset; if your Helm chart, operator custom resource, or pod template sets a different account, use that name with -z.
For example, when workloads run as default:
To discover the account name for an existing pod:
An empty result means that the namespace default service account is used. Grant SCC separately for each distinct service account that runs operator-managed media functions, LipSync NIM, or sample chart pods in this namespace.
Without this step, pods might fail with security context constraint errors.
Namespace Scope
After the namespace exists and SCC permissions are in place, copy namespace-scoped resources into the deployment namespace when they already exist elsewhere on the cluster (commonly the default project).
The Multus network name you set in Helm (network.name or global.network.name) must match the NetworkAttachmentDefinition you deploy or copy into this namespace. For details on how to choose and configure that name, refer to High-Speed Network Configuration.
1. Copy NetworkAttachmentDefinitions (NADs)
NADs are namespace-scoped resources.
Check available NADs:
If the required NADs exist in another namespace (commonly default), copy them into the deployment namespace:
Without this step, pods might fail with the following error:
2. Copy Rivermax License Secret
If the rivermax-license secret exists in another namespace (commonly default), copy it into the deployment namespace:
On Red Hat OpenShift, you can use oc instead of kubectl in the commands above.
Scheduler Requirements for NUMA-aware Clusters
The sender, LipSync NIM, and receiver workloads request dedicated CPU, GPU, memory, and hugepages resources. Resource requirements vary by component. The following example shows the LipSync NIM container configuration:
On clusters configured with strict NUMA policies (for example, topologyManagerPolicy=single-numa-node), a topology-aware scheduler might be required to successfully place the sender, NIM, and receiver pods.
The Helm chart exposes schedulerName as a configurable parameter.
For NUMA-aware deployments, configure schedulerName as follows:
OpenShift users can install the NUMA Resources Operator (NRO), which provides topo-aware-scheduler.
On clusters without a topology-aware scheduler, you can configure schedulerName as follows:
This configuration assumes that the cluster topology can satisfy the workload resource requirements.
If pods remain in Pending state with FailedScheduling events mentioning NUMA alignment or topology constraints, verify the following:
- Topology Manager configuration
- Availability of hugepages
- Alignment of CPU and GPU resources
- Scheduler configuration
Access NGC and Helm Charts
An NGC account and an NGC API key are required to authenticate the CLI, pull container images and Helm charts from NVIDIA registries, and create cluster pull secrets as described in License and Secrets Management.
NGC Authentication
Generate an API Key
An NGC API key is required to access NGC resources. You can generate a key at https://org.ngc.nvidia.com/setup/api-keys.
When creating an NGC API Personal key, ensure that at least NGC Catalog is selected from the Services Included dropdown. You can include more services if this key is to be reused for other purposes.
Personal keys allow you to configure an expiration date, revoke or delete the key using an action button, and rotate the key as needed. For more information about key types, refer to NGC API Keys in the NGC User Guide.
Export the NGC API Key
To pull container images and model artifacts from NGC, use the NGC_API_KEY environment variable when authenticating with the Helm registry and creating cluster secrets as described in the following sections.
The simplest way to create the NGC_API_KEY environment variable is to export it in your terminal:
Run one of the following commands to make the key available at startup:
Other, more secure options include saving the value in a file, so that you can retrieve with cat $NGC_API_KEY_FILE, or using a password manager.
Log In to the NGC Registry
Log in to the NGC container and Helm registry before pulling charts or images:
License and Secrets Management
Rivermax License
Rivermax is an optimized networking SDK that uses ConnectX and BlueField DPU hardware-streaming acceleration and supports GPUDirect, in bare metal and virtualized environments. Rivermax is required by Holoscan for Media applications to comply with the timing and traffic flow requirements of SMPTE ST 2110.
Request a development license at Rivermax Download. When the license file is available, create a Kubernetes secret from it:
The Helm chart mounts this secret into the container at /opt/mellanox/rivermax.
On Red Hat OpenShift, replace kubectl with oc.
Image Pull Secret
Create a secret so the cluster can pull images from nvcr.io:
On Red Hat OpenShift, replace kubectl with oc.
Example:
<secret-name>: Name for the image pull secret.<NGC-API-KEY>: The NGC API key for the org that hosts the images.<your-email>: The email address associated with the NGC account.<your-namespace>: The Kubernetes namespace in which applications are deployed; oftendefaultwhen getting started.
Model Pull Secret
Model artifacts are downloaded by the NIM at runtime using an API key carried in a generic secret, separate from the image pull secret discussed earlier:
Example:
On Red Hat OpenShift, replace kubectl with oc.
<secret-name>: Name for the model pull secret.<NGC-API-KEY>: The NGC API key for the org that hosts model artifacts.
High-Speed Network Configuration
SMPTE ST 2110 media transport uses a dedicated high-speed network attachment provisioned on the cluster. The network attachment name must match the NetworkAttachmentDefinition configured by your cluster administrator.
Set the network attachment name in the Helm values for each component in the pipeline. A single attachment is configured as follows:
For multiple network attachments, use the list format:
For networks with static IP address management, the ip property is required in addition to the network name.
To ensure correct media routing, the network attachment name must be the same across all components in the pipeline—sender, NIM service, and receiver.
Chrome Remote Desktop
When LipSync is deployed with NMOS enabled, streams are connected and managed through the NMOS Connection Manager (a web UI). On Holoscan for Media clusters, access to that UI typically requires a browser that can reach the cluster network. Chrome Remote Desktop provides a remote graphical session for accessing that UI.
For information about installation and setup, refer to the Chrome Remote Desktop section of Manual Deployment in the Holoscan for Media user guide.
Security Context
The NIM container requires the following Linux capabilities to operate correctly:
These capabilities are set in the Helm values under containerSecurityContext or in the NIM operator custom resource under spec.parameters.securityContext. For details, refer to Configuration Reference.
See Also
- Installation: Instructions for demo, service, and operator Helm install instructions.
- Configuration Reference: Helm, operator, and environment variable tables with defaults and allowed values.