> This page is for NVIDIA Video Super Resolution NIM, version 1.0.10 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 1.0.10 (Latest) (default): https://docs.nvidia.com/nim/maxine/vsr/1.0.10/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nim/maxine/llms.txt.

# 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](https://docs.nvidia.com/holoscan-for-media/latest/index.html) user guide.

Before deploying VSR NIM for ST 2110, verify the requirements in the [ST 2110 Support Matrix](/nim/maxine/vsr/st2110/support-matrix).

## Prerequisites

| Requirement | Details | Reference |
|---|---|---|
| Kubernetes cluster | Holoscan for Media–capable Kubernetes or Red Hat OpenShift cluster. | [Support Matrix](/nim/maxine/vsr/st2110/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](/nim/maxine/vsr/st2110/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](#openshift-security-context-constraint) |
| NGC account and API key | Required for CLI authentication, chart pulls, image pulls, and image pull secrets. | [NGC Authentication](#ngc-authentication) |
| Rivermax license | Required for SMPTE ST 2110 streaming. | [Rivermax License](#rivermax-license) |
| High-speed network attachment | `NetworkAttachmentDefinition` resources for ST 2110 media traffic. | [High-Speed Network Configuration](#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](#namespace-scope) |
| OpenShift Security Context Constraint | An SCC that grants the NIM the four Linux capabilities and `allowPrivilegeEscalation: true`. | [Security Context](#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](#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](#chrome-remote-desktop) |

## NGC Authentication

Generate an NGC API key from [NGC API Keys](https://org.ngc.nvidia.com/setup/api-keys). When creating a personal key, select at least **NGC Catalog** from the **Services Included** dropdown.

Export the key:

```bash
export NGC_API_KEY=<value>
```

Log in to the NGC Helm registry before pulling charts:

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

## Rivermax License

[Rivermax](https://docs.nvidia.com/holoscan-for-media/latest/user-guide/getting-help/rivermax-st-2110.html#rivermax-help) 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](https://developer.nvidia.com/networking/rivermax-getting-started). When the license file is available, create a Kubernetes secret in the workload namespace:

```bash
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`:

```bash
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](/nim/maxine/vsr/st2110/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:

```bash
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:

```bash
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:

```bash
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](https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/authentication_and_authorization/managing-pod-security-policies) 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`.
</Note>

## 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:

```bash
kubectl get network-attachment-definitions -A
```

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

```text
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:

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

If the required attachments exist in another namespace, such as `default`, copy them into the workload namespace:

```bash
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:

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

---

(scheduler-and-numa-topology)=
## 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](https://docs.nvidia.com/holoscan-for-media/latest/user-guide/platform-setup/prod-automation/index.html) provisions both the topology-aware scheduler and the kubelet topology-manager policy. On clusters not provisioned this way, install the [NUMA Resources Operator](https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/scalability_and_performance/cnf-numa-aware-scheduling) (Red Hat OpenShift), which exposes a secondary scheduler named `topo-aware-scheduler` and `NodeResourceTopology` custom resources.
</Note>

### 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:

```bash
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:

```bash
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](/nim/maxine/vsr/st2110/helm#network-attachments) and [Deploy with the Operator](/nim/maxine/vsr/st2110/operator#high-speed-network-resource-pools).

### Troubleshooting

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

```text
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:

```bash
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](https://docs.nvidia.com/holoscan-for-media/latest/user-guide/app-deployment/manual/manual-deployment.html#chrome-remote-desktop) section of the Holoscan for Media user guide.

## Next Steps

- [Deploy with Helm](/nim/maxine/vsr/st2110/helm)
- [Deploy with the Operator](/nim/maxine/vsr/st2110/operator)