Kubernetes Operator Chart#

Overview#

The nvidia-lipsync-h4m-operator Helm chart installs the LipSync Kubernetes operator. The operator watches NvidiaLipsyncMediaFunction custom resources and reconciles the required components, including the LipSync NIM deployment, SDP ConfigMaps, and status.

Operator: Deploys the controller and CRDs only. It does not create a NvidiaLipsyncMediaFunction resource or deploy the LipSync NIM workload. After installation, apply a custom resource (CR) to provision the NIM.
Operand: Each NvidiaLipsyncMediaFunction custom resource defines and drives a single LipSync NIM workload based on the specified inputs, outputs, and parameters.

Installation#

Prerequisites#

Complete all prerequisite steps (Rivermax license, image pull and model pull secrets, GPU node, Multus attachment for SMPTE ST 2110) before running helm install. For more information, refer to Getting Started.

Operator Installation#

If not already done, add the Helm repository and pull the chart:

helm pull nim-repo/nvidia-lipsync-h4m-operator --version 1.0.0

For the full repository setup, refer to Pull Helm Charts.

Helm Installation#

The chart installs the operator Deployment and registers the NvidiaLipsyncMediaFunction CRD. For all available Helm values and --set keys, refer to Operator Configuration.

The chart expects a pre-created image pull secret for nvcr.io (default name ngc-secret-key). If your secret names differ, override as follows:

Note: The same image pull secret is used for the operator, the custom resource, and the media function container image.

The model pull secret and node hostname are set on the custom resource, not Helm values (spec.parameters.ngcApiKeySecret, spec.parameters.nodeSelector). Refer to Custom Resource Installation.

helm install lipsync-operator \
  nvidia-lipsync-h4m-operator-1.0.0.tgz \
  --set imagePullSecrets[0].name=<ngc-image-pull-secret>

When the defaults match your cluster, you can use the following command:

helm install lipsync-operator \
  ./nvidia-lipsync-h4m-operator-1.0.0.tgz

Wait Until the Controller Is Ready#

kubectl rollout status deployment/lipsync-operator-controller-manager --timeout=180s

On Red Hat OpenShift, replace kubectl with oc.

Custom Resource Installation#

After the operator controller is ready, save a manifest (for example, lipsync-media-function.yaml) and change the following parameters to match your cluster:

Configuration	What to Set	Notes
GPU node	`spec.parameters.nodeSelector`	Labels for the node that runs the LipSync NIM pod (for example, `kubernetes.io/hostname`).
Model pull secret	`spec.parameters.ngcApiKeySecret` (`name`, `key`)	Secret for downloading models.
Network attachment	`spec.parameters.highSpeedNetwork`	Multus network for media traffic. Refer to High-Speed Network Configuration.
Pipeline I/O	`spec.inputs` / `spec.outputs`	NMOS or SDP control and RTP transport configuration for your deployment.
Persistent storage (optional)	`spec.parameters.nimModelCache` / `spec.parameters.serverLogs`	Optional PVC-backed model cache and logs.

Apply the CR:

kubectl apply -f lipsync-media-function.yaml

Applying the CR reconciles and starts the LipSync NIM in NMOS mode. For NMOS Connection Manager UI access and setup steps, refer to Chrome Remote Desktop.

Example Manifest (lipsync-media-function.yaml)#

Reference a custom resource with a placeholder node name, model-download-api-key for model download, and common video format defaults.

apiVersion: nvidia.com/v1alpha1
kind: NvidiaLipsyncMediaFunction
metadata:
  name: nvidia-lipsync-h4m-media-function
spec:
  parameters:
    nodeSelector:
      kubernetes.io/hostname: <gpu-node-name>
    schedulerName: topo-aware-scheduler
    highSpeedNetwork:
      - name: media-a-tx-net
    ngcApiKeySecret:
      name: model-download-api-key
      key: NGC_API_KEY
    securityContext:
      runAsUser: 1000
      runAsGroup: 1000
      runAsNonRoot: true
      allowPrivilegeEscalation: true
      capabilities:
        add:
          - IPC_LOCK
          - NET_RAW
          - SYS_NICE
          - DAC_READ_SEARCH
        drop:
          - ALL
    label: Nvidia-LipSync-NIM-Media-Function
    description: NVIDIA LipSync NIM
    loggingLevel: 3
    modelHeadMovementSpeed: 0
    inputAncillaryDataEnabled: false
    outputBoundingBoxEnabled: false
    nimModelCache:
      enabled: false
      size: 10Gi
      storageClassName: ""
    serverLogs:
      enabled: false
      size: 5Gi
      storageClassName: ""

  inputs:
    video_input:
      control:
        nmos: {}
      transport:
        rtp: {}
      format:
        video:
          frame_width: 1920
          frame_height: 1080
          frame_rate: "30"
          media_type: "video/raw"
          interlace_mode: progressive
          color_sampling: "YCbCr-4:2:2"
          component_depth: 10
          colorspace: "BT709"
          transfer_characteristic: "SDR"

    audio_input:
      control:
        nmos: {}
      transport:
        rtp:
          packet_time: 1
      format:
        audio:
          sample_rate: 48000
          channel_count: 1
          sample_depth: 24
          media_type: audio/L24

  outputs:
    video_output:
      control:
        nmos: {}
      transport:
        rtp: {}
      format:
        video:
          frame_width: 1920
          frame_height: 1080
          frame_rate: "30"
          media_type: "video/raw"
          interlace_mode: progressive
          color_sampling: "YCbCr-4:2:2"
          component_depth: 10
          colorspace: "BT709"
          transfer_characteristic: "SDR"

Extended Parameters (Optional)#

As needed, you can add optional spec.parameters fields, including resources (CPU, memory, GPU, hugepages) and nimLogs / nimModelCache PVC settings. For field-by-field details, refer to Operator Configuration in the Configuration Reference. For PVC configuration, refer to Advanced Usage.

Verify and Check Logs#

After applying the CR:

# List LipSync Media Function CRs and age/status
kubectl get nvidialipsyncmediafunctions

# List pods created and managed by the LipSync operator
kubectl get pods -l app.kubernetes.io/managed-by=lipsync-operator

Inspect CR status:

# Show status conditions for one CR
kubectl get nvidialipsyncmediafunction nvidia-lipsync-h4m-media-function \
  -o json | jq '.status.conditions'

# Confirm the CRD is installed
kubectl get crd nvidialipsyncmediafunctions.nvidia.com

For workload logs:

kubectl logs deployment/nvidia-lipsync-h4m-media-function

For operator logs:

kubectl logs deployment/lipsync-operator-controller-manager

Uninstall#

First, delete all NvidiaLipsyncMediaFunction instances so the operator can remove managed deployments and ConfigMaps; then uninstall the Helm release. Delete the CRD cluster-wide only if coordinated with cluster administrators; it affects all namespaces.

kubectl delete nvidialipsyncmediafunctions.nvidia.com --all
helm uninstall lipsync-operator
# Optional - removes the custom API cluster-wide:
kubectl delete crd nvidialipsyncmediafunctions.nvidia.com

Troubleshooting#

For troubleshooting and known limitations, refer to Advanced Usage.