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.

Requirement	Details	Reference
Kubernetes cluster	Kubernetes or Red Hat OpenShift.	Support Matrix
OpenShift setup	Create the target namespace and grant SCC permissions to each service account your workloads use (often `default`).	OpenShift Setup
Namespace scope	Copy NADs and the `rivermax-license` secret into the deployment namespace when they exist in another project (for example, `default`).	Namespace Scope
NGC account and API key	Required for CLI authentication, image and chart pulls, and creating image pull and model pull secrets.	NGC Authentication
Rivermax license	Required for SMPTE ST 2110 streaming.	Rivermax License
High-speed network attachment	A `NetworkAttachmentDefinition` for SMPTE ST 2110 provisioned by the cluster administrator.	High-Speed Network Configuration
NMOS registry (optional)	Required only when using NMOS for dynamic stream connection management.	—
Chrome Remote Desktop (when using NMOS)	Required to reach the NMOS Connection Manager UI in Holoscan for Media setups.	Chrome Remote Desktop
Topology-aware scheduler (when applicable)	Required on some clusters with strict NUMA policies so sender, NIM, and receiver pods in the sample chart can schedule.	Scheduler Requirements for NUMA-aware Clusters

OpenShift Setup#

Complete the following steps before deployment.

1. Create Namespace#

kubectl create namespace <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.

oc adm policy add-scc-to-user privileged -z <service-account-name> -n <namespace>

For example, when workloads run as default:

oc adm policy add-scc-to-user privileged -z default -n <namespace>

To discover the account name for an existing pod:

kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.spec.serviceAccountName}{"\n"}'

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:

kubectl get net-attach-def -A

If the required NADs exist in another namespace (commonly default), copy them into the deployment namespace:

NS_DST=<namespace>

for nad in $(kubectl get net-attach-def -n default -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{end}'); do
  kubectl get net-attach-def "$nad" -n default -o json | jq --arg ns "$NS_DST" '
    del(.metadata.uid,
        .metadata.resourceVersion,
        .metadata.creationTimestamp,
        .metadata.generation,
        .metadata.managedFields) |
    .metadata.namespace = $ns
  ' | kubectl apply -f -
done

Without this step, pods might fail with the following error:

NetworkAttachmentDefinition "<name>" not found

2. Copy Rivermax License Secret#

If the rivermax-license secret exists in another namespace (commonly default), copy it into the deployment namespace:

NS_DST=<namespace>

kubectl get secret rivermax-license -n default -o json | jq --arg ns "$NS_DST" '
  del(.metadata.uid,
      .metadata.resourceVersion,
      .metadata.creationTimestamp,
      .metadata.managedFields,
      .metadata.ownerReferences) |
  del(.metadata.annotations."kubectl.kubernetes.io/last-applied-configuration") |
  .metadata.namespace = $ns
' | kubectl apply -f -

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:

resources:
  limits:
    cpu: 8
    hugepages-2Mi: 4Gi
    memory: 8Gi
    nvidia.com/gpu: 1
  requests:
    cpu: 8
    hugepages-2Mi: 4Gi
    memory: 8Gi
    nvidia.com/gpu: 1

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:

schedulerName: topo-aware-scheduler

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:

schedulerName: default-scheduler

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.

Note

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:

export NGC_API_KEY=<value>

Run one of the following commands to make the key available at startup:

# If using bash
echo "export NGC_API_KEY=<value>" >> ~/.bashrc

# If using zsh
echo "export NGC_API_KEY=<value>" >> ~/.zshrc

Note

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:

helm registry login nvcr.io --username '$oauthtoken' --password $NGC_API_KEY

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:

kubectl create secret generic rivermax-license \
  --from-file=rivermax.lic \
  -n <your-namespace>

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:

kubectl create secret docker-registry <secret-name> \
  --docker-server=nvcr.io \
  '--docker-username=$oauthtoken' \
  --docker-password=<NGC-API-KEY> \
  --docker-email=<your-email> \
  -n <your-namespace>

On Red Hat OpenShift, replace kubectl with oc.

Example:

oc create secret docker-registry ngc-secret-key \
  --docker-server=nvcr.io \
  '--docker-username=$oauthtoken' \
  --docker-password=MY-NGC-API-KEY \
  --docker-email=test@nvidia.com

<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; often default when 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:

kubectl create secret generic <secret-name> \
  --from-literal=NGC_API_KEY=<NGC-API-KEY> \
  -n <your-namespace>

Example:

kubectl create secret generic model-download-api-key \
  --from-literal=NGC_API_KEY=MY-NGC-API-KEY

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:

highSpeedNetwork:
  name: "media-a-tx-net"

For multiple network attachments, use the list format:

highSpeedNetwork:
  - name: "media-a-tx-net"
  - name: "media-b-tx-net-static"
    ip: "198.51.100.3/24"

For networks with static IP address management, the ip property is required in addition to the network name.

Note

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:

Capability	Purpose
`IPC_LOCK`	Lock memory pages; required for hugepage allocation by Rivermax.
`NET_RAW`	Use raw sockets; required by Rivermax for SMPTE ST 2110.
`SYS_NICE`	Set process and thread CPU affinity; required by Rivermax.
`DAC_READ_SEARCH`	Read files across permission boundaries during startup.

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.

Getting Started#

Holoscan for Media#

Prerequisites#

OpenShift Setup#

1. Create Namespace#

2. Grant SCC Permission#

Namespace Scope#

1. Copy NetworkAttachmentDefinitions (NADs)#

2. Copy Rivermax License Secret#

Scheduler Requirements for NUMA-aware Clusters#

Access NGC and Helm Charts#

NGC Authentication#

Generate an API Key#

Export the NGC API Key#

Log In to the NGC Registry#

License and Secrets Management#

Rivermax License#

Image Pull Secret#

Model Pull Secret#

High-Speed Network Configuration#

Chrome Remote Desktop#

Security Context#

See Also#