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
Check the Support Matrix to verify that the required hardware and software are available before proceeding.
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 both 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.
<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.
(openshift-setup)=
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, NIM, or sample chart pods in this namespace.
Without this step, pods might fail with security context constraint errors.
(namespace-scope)=
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).
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)=
Scheduler Requirements for NUMA-Aware Clusters
Some clusters enforce NUMA-aware scheduling policies that prevent pods from being scheduled by the default Kubernetes scheduler when they request resources such as hugepages, GPUs, or CPU sets. In these environments, the topo-aware-scheduler is required for the sender, NIM service, and receiver pods to schedule correctly.
Confirm whether your cluster uses a topology-aware scheduler:
If the scheduler is present, set schedulerName: topo-aware-scheduler in your Helm values or pass it as an override:
For the end-to-end sample chart, use the global override to apply it to all components at once:
If the scheduler is not present or not required on your cluster, the default Kubernetes scheduler is used and no action is needed.
(chrome-remote-desktop)=
Chrome Remote Desktop
When Active Speaker Detection 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 installation.
- Configuration Reference — Helm, operator, and environment variable tables with defaults and allowed values.