Getting Started#

This guide covers prerequisites that apply to VSR NIM ST 2110 deployments on Holoscan for Media.

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.

Before deploying VSR NIM for ST 2110, verify the requirements in the ST 2110 Support Matrix.

Prerequisites#

Requirement	Details	Reference
Kubernetes cluster	Holoscan for Media–capable Kubernetes or Red Hat OpenShift cluster.	Support Matrix
GPU and driver	Ada-generation or later NVIDIA GPU with NVIDIA Driver 590.33 or later and CUDA 13.1 or later.	Support Matrix
CLI	`kubectl` or `oc` access to the target cluster.	—
Helm	Helm v3.x.	—
OpenShift setup	Create the target namespace and grant SCC permissions to each service account your workloads use (often `default`).	OpenShift Security Context Constraint
NGC account and API key	Required for CLI authentication, chart pulls, image pulls, and image pull secrets.	NGC Authentication
Rivermax license	Required for SMPTE ST 2110 streaming.	Rivermax License
High-speed network attachment	`NetworkAttachmentDefinition` resources for ST 2110 media traffic.	High-Speed Network Configuration
Namespace scope	`NetworkAttachmentDefinition` resources are namespace-scoped; copy them into the workload namespace when they exist in another namespace (for example, `default`).	Namespace Scope
OpenShift Security Context Constraint	An SCC that grants the NIM the four Linux capabilities and `allowPrivilegeEscalation: true`.	Security Context
Topology-aware scheduler (when applicable)	Required on clusters with `topologyManagerPolicy: single-numa-node` so that sender, NIM, and receiver pods can co-locate GPU, SR-IOV virtual functions, hugepages, and CPU on the same NUMA zone.	Scheduler and NUMA Topology
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

NGC Authentication#

Generate an NGC API key from NGC API Keys. When creating a personal key, select at least NGC Catalog from the Services Included dropdown.

Export the key:

export NGC_API_KEY=<value>

Log in to the NGC Helm registry before pulling charts:

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

Rivermax License#

Rivermax is an optimized networking SDK that uses NVIDIA 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 in the workload namespace:

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

On Red Hat OpenShift, replace kubectl with oc.

Image Pull Secret#

Create a secret so the cluster can pull private 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 <namespace>

On Red Hat OpenShift, replace kubectl with oc.

<secret-name> is the image pull secret name, such as ngc-secret-h4m.
<NGC-API-KEY> is your NGC API key.
<your-email> is the email address associated with your NGC account.
<namespace> is the Kubernetes namespace for the workload.

Security Context#

To operate correctly, the VSR NIM ST 2110 workload requires allowPrivilegeEscalation: true and the following Linux capabilities:

Capability	Purpose
`IPC_LOCK`	Lock memory pages for Rivermax and hugepage-backed media processing.
`NET_RAW`	Use raw sockets for SMPTE ST 2110 media networking.
`SYS_NICE`	Set process and thread scheduling priority or affinity for media processing.
`DAC_READ_SEARCH`	Read files across permission boundaries during startup.

These values are set in the Helm values under containerSecurityContext or in the operator custom resource under spec.parameters.securityContext. For an operator custom resource example, refer to Deploy with the Operator.

OpenShift Security Context Constraint#

On Red Hat OpenShift, the default restricted-v2 Security Context Constraint denies allowPrivilegeEscalation: true and the capabilities mentioned in the previous section. By default, sender, NIM, and receiver pods run as the default ServiceAccount in the deployment namespace, so an SCC that permits these settings must be bound to that ServiceAccount. If your Helm values, operator custom resource, or pod templates set a different serviceAccountName, grant the SCC to that account instead.

To confirm which ServiceAccount a pod uses, run the following command:

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

An empty result means that the pod uses the namespace default ServiceAccount.

For development and evaluation, the simplest option is to bind the built-in privileged SCC to the deployment namespace:

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

If your pods use a different account, replace default with the actual ServiceAccount name:

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

For production, prefer a least-privilege SCC that grants only allowPrivilegeEscalation: true and the four capabilities mentioned in the previous section. Refer to Managing security context constraints in the OpenShift documentation.

Note

If the SCC binding is missing, pod creation fails with an admission error from the SCC validator. For example:

unable to validate against any security context constraint: provider "restricted-v2": Forbidden: ... capabilities.add: Invalid value: "IPC_LOCK": capability may not be added

Inspect with oc get events -n <namespace> --sort-by=.lastTimestamp.

High-Speed Network Configuration#

SMPTE ST 2110 media transport uses dedicated high-speed network attachments provisioned on the cluster. The network attachment names must match the NetworkAttachmentDefinition resources configured by the cluster administrator.

SR-IOV lets a physical NIC expose virtual functions that can be assigned to pods for high-throughput media traffic. Multus lets Kubernetes attach those additional media networks to a pod in addition to the default cluster network.

Check available network attachments:

kubectl get network-attachment-definitions -A

The VSR NIM ST 2110 samples use one receive attachment and one transmit attachment by default:

media-a-rx-net
media-a-tx-net

VSR NIM receives and transmits ST 2110 traffic, so the media function pod uses both receive and transmit network attachments.

These names are sample defaults. Replace them with the NetworkAttachmentDefinition names provisioned for your cluster. The attachment names do not have to describe RX-only or TX-only physical networks; choose attachments that carry the VSR input and output traffic required by your cluster topology.

Namespace Scope#

NetworkAttachmentDefinition resources are namespace-scoped, and Multus looks them up in the same namespace as the pod. Every network attachment referenced by the Helm chart or operator CR must exist in the workload namespace.

Check which network attachments exist in the target namespace:

kubectl get net-attach-def -n <namespace>

If the required attachments exist in another namespace, such as default, copy them into the workload 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

On Red Hat OpenShift, replace kubectl with oc.

If a referenced attachment is missing from the workload namespace, pod admission can fail with NetworkAttachmentDefinition "<name>" not found. Inspect namespace events with the following command:

oc get events -n <namespace> --sort-by=.lastTimestamp

Scheduler and NUMA Topology#

The VSR NIM service pod requests a GPU, hugepages, CPU, and ST 2110 media interfaces. The sample sender and receiver pods can also request SR-IOV virtual functions, and the receiver requests a GPU. These resources perform best when co-located on the same NUMA zone. On Holoscan for Media production clusters, use schedulerName: topo-aware-scheduler for ST 2110 workloads so that NUMA alignment is computed at scheduling time. For this setting to take effect, the cluster needs a topology-aware scheduler registered under that name and a kubelet configured with topologyManagerPolicy: single-numa-node.

To override schedulerName on clusters without a topology-aware scheduler, use the matching knob for your deployment path:

Service chart: Keep schedulerName unset or empty in your values file, or pass --set schedulerName="".
Sample chart: Set h4m.schedulerName: "" for a fleet-wide override. Also set nvidia-vsr-nim-h4m-service.schedulerName: "" when overriding the VSR NIM service subchart directly.
Operator custom resource: Omit spec.schedulerName or set it to an available scheduler on the NvidiaVsrNimMediaFunction CR.

Note

The Holoscan for Media production automation provisions both the topology-aware scheduler and the kubelet topology-manager policy. On clusters not provisioned this way, install the NUMA Resources Operator (Red Hat OpenShift), which exposes a secondary scheduler named topo-aware-scheduler and NodeResourceTopology custom resources.

Verify Per-NUMA Capacity#

Before deployment, confirm that a NUMA zone has both a free GPU and the SR-IOV virtual functions required by the network pools referenced by the chart or operator custom resource:

oc get noderesourcetopologies <node> -o yaml

In the output, find a zone whose resources list reports available capacity for both nvidia.com/gpu and the SR-IOV pool. The following command determines which pool a given network attachment resolves to:

oc get net-attach-def <name> -n <namespace> \
  -o jsonpath='{.metadata.annotations.k8s\.v1\.cni\.cncf\.io/resourceName}{"\n"}'

VSR NIM has separate input and output media interfaces. On clusters that require single-numa-node placement, configure the VSR service rxName, txName, rxPoolResource, txPoolResource, and pool counts so the GPU and requested virtual functions can be allocated together. If both VSR interfaces must use the same SR-IOV pool, use the same network attachment for rxName and txName, request two virtual functions from that pool, and keep input.video.localInterfaceName and output.video.localInterfaceName aligned with the rendered pod interfaces. Examples are provided in Deploy with Helm and Deploy with the Operator.

Troubleshooting#

If a pod stays Pending with the following event, the topology-aware scheduler could not satisfy NUMA alignment on any node:

Warning  FailedScheduling  topo-aware-scheduler
  0/N nodes are available: 1 cannot align container.

Likely causes:

The NUMA zone hosting the requested SR-IOV pool has no free GPU. Use the capacity check shown earlier to find a zone with both a free nvidia.com/gpu and a free virtual function in the matching SR-IOV pool.
The kubelet on the target node is not set to topologyManagerPolicy: single-numa-node.
The cluster has no scheduler registered under the name topo-aware-scheduler. Verify with kubectl get pods -A | grep topo-aware-scheduler or check with the cluster administrator.
The VSR input and output network attachments request SR-IOV pools from different NUMA zones. Use the VSR same-pool example shown earlier when your cluster exposes one NUMA-local pool for both VSR interfaces.

If you override schedulerName to the cluster default, the failure mode changes. The default scheduler ignores Topology Manager constraints, so on a NUMA-booked cluster the kubelet can reject the chosen node post-bind with TopologyAffinityError: Resources cannot be allocated with Topology locality rather than a FailedScheduling event. On NUMA-spacious clusters the pod can schedule and run, but cross-NUMA placement is possible.

Inspect pod events with the following command:

oc describe pod <pod-name> -n <namespace>

Chrome Remote Desktop#

When using NMOS mode, stream connections are managed through the NMOS Connection Manager UI. On Holoscan for Media clusters, Chrome Remote Desktop is commonly used to access that UI. For setup instructions, refer to the Chrome Remote Desktop section of the Holoscan for Media user guide.

Getting Started#

Holoscan for Media#

Prerequisites#

NGC Authentication#

Rivermax License#

Image Pull Secret#

Security Context#

OpenShift Security Context Constraint#

High-Speed Network Configuration#

Namespace Scope#

Scheduler and NUMA Topology#

Verify Per-NUMA Capacity#

Troubleshooting#

Chrome Remote Desktop#

Next Steps#