OVDC: Configure#

This guide provides detailed information on the Omniverse Derived Cache (OVDC) component and its use in a self-hosted NVCF cluster.

OVDC reduces scene load time and improves performance when properly configured and sized for the workload. Derived data generation is computationally expensive and time-consuming. OVDC trades network bandwidth for compute time by caching derived data, allowing multiple GPUs to share pre-generated content.

values.yaml has two halves, and the distinction matters: settings.* mirrors the application’s own config.toml schema and is rendered key-by-key into the chart’s ConfigMap—every key there must be one the binary deserializes, and the schema is closed (an unrecognised key fails the render). Everything else is ordinary Kubernetes-level chart configuration.

Base Configuration#

OVDC requires some configuration to be properly installed. Create a file on your local machine called values.yaml. A base configuration is provided in the following dropdown.

image:
  pullSecrets:

    - name: regcred

replicas: 1
selfAntiAffinity: true
affinity:
  nodeAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:

      - weight: 100
        preference:
          matchExpressions:

            - key: node-type
              operator: In
              values:

                - compute

resources:
  requests:
    # Should cover cacheSize + blockCacheSize + ~6GB TCP buffer. Write buffers
    # share the block cache budget when useWriteBufferManager is true (the
    # default); add them on top only if you set it to false.
    memory: 56G

storage:
  volume:
    size: 330Gi
    storageClassName: "gp3"

presets:
  cpu: 8
  ram: "48GB"

settings:
  logFormat: "json"
  logLevel: "info"
  store:
    maxSize: AUTO

presets.cpu and presets.ram are the recommended way to size settings.engine—see Sizing Presets below for the full tables and how to tune settings.engine directly instead.

Base Configuration Field Reference#

Field	Type	Required	Default	Description
`image.pu llSecrets`	list of `{name}`	No	`[{name: regcred}]`	Kubernetes `imagePu llSecrets` entries; each `name` must reference an existing ` kubernetes .io/dockerc onfigjson` Secret in the target namespace.
` replicas`	integer	No	`1`	Number of OVDC pods to deploy.
`selfAnt iAffinity`	boolean	No	`true`	When `true`, the scheduler prefers to place OVDC pods on nodes that do not already run one.
` affinity`	Kubernetes affinity object	No	`{}`	Merged over the chart’s self-an ti-affinity rule; values set here win on conflict.
`resou rces.reques ts.memory`	quantity string	No	`56G`	Should cover `setti ngs.engine. cacheSize` + ` settings.e ngine.block CacheSize` + ~6GB TCP buffer. Write buffers share the block cache budget when `settin gs.engine.u seWriteBuff erManager` is `true` (the default); add them separately only if it is `false`.
` storage.vo lume.size`	quantity string	No	`300Gi`	Size of the Persistent VolumeClaim created per pod. `` volumeClaim Templates`` are immutab le—changing this on an existing release is rejected on upgrade.
`` storage.vol ume.storage ClassName``	string	No	`ma naged-csi`	Must support `ReadW riteOnce`; select a class with sufficient IOPS /throughput (see the 800 MB/s guidance above).
`pr esets.cpu`	integer enum	No	`~` (unset)	One of ` 1`-`8`. Overrides `settin gs.engine.i ncreasePara llelism`/` threadsHig h`/`threa dsLow`—see Sizing Presets below.
`pr esets.ram`	string enum	No	`~` (unset)	One of `4GB`, `6GB`, `7GB`, `8GB`, `12GB`, `16GB`, `24GB`, `32GB`, `48GB`, `64GB`. Overrides `se ttings.engi ne.cacheSiz e`/`block CacheSize` and `settings. engine.blob sCf.max_wri te_buffer_n umber`—see Sizing Presets below.
`settings. logFormat`	string enum	No	`json`	One of `json`, `human`, `human_ no_color`.
`settings .logLevel`	string enum	No	`info`	One of `error`, `warn`, `info`, `debug`, `trace`, `off`.
`se ttings.stor e.maxSize`	quantity string or `"AUTO"`	No	`AUTO`	RocksDB on-disk target. `AUTO` derives from ` storage.vo lume.size` less `min(20 %, 100GB)` headroom; requires `storage.v olume.enabl ed: true`.
`sett ings.teleme try.prometh eusMetricsE xposition`	boolean	No	`true`	When `true`, starts the Prometheus metrics HTTP service on `pr ometheusMet ricsPort`.
`settings. telemetry.p rometheusMe tricsPort`	integer	No	`3051`	Port the Prometheus metrics service binds.

For the complete set of settings.* keys, including RocksDB db / cf / block option maps, gRPC, TLS, JWT, and OpenTelemetry configuration, see the full values reference.

Complete Configuration Reference#

The base configuration above covers the essential settings for most deployments. For advanced configuration options or to explore all available settings, refer to the complete values file below. This reference includes all configuration options available in the OVDC Helm chart, including advanced settings for TLS, OpenTelemetry, and resource management.

Full Configuration - View the full reference values.yaml file.

1. Provision and Scale#

Proper provisioning and scaling are critical for OVDC performance. When undersized or misconfigured for the workload, simulations will slow down or even fail.

OVDC’s data directory is typically a network-attached PersistentVolumeClaim rather than local NVMe, and its sustained throughput is the binding operational constraint:

Important

Provision network-attached PVCs for at least 800 MB/s sustained throughput. Below that, background compaction by RocksDB (the embedded log-structured storage engine OVDC uses to persist cached data) cannot retire the write amplification a loaded node generates, the backlog grows, and the store spends its time in write stalls regardless of tuning. Many cloud volume types offer burst credits that exhaust under sustained load—size for the sustained figure, not the burst figure.

Reference sizing for a single OVDC replica:

Resource	Guidance
Compute SKU	Comparable to Azure `E8s_v5`–`E20s_v5` or AWS `r8g.12xlarge`–`24xlarge`
Memory	~8 GB DRAM per vCPU
Remote disk	2x–8x the total scene data
Network	Node NICs ≥ 12.5 Gbps
Throughput	~60,000 requests/second per instance; scale replicas linearly

AWS EKS Example#

Assuming the SKU for compute nodes is r8g.12xlarge.

SKU	vCPU	RAM	NIC
r8g.12xlarge (compute)	48	384 G	20 Gbps

A single OVDC pod should be placed on each compute node. The goal is to expand network and storage-throughput capability with each pod, distributing cache load across multiple nodes.

Schedule ‘3’ OVDC Pods

yaml title="values.yaml" replicas: 3

2. Memory Configuration#

OVDC memory configuration includes the Kubernetes container resources block, along with engine-level cache settings under settings.engine. The default configuration allocates memory for the row cache, block cache, and write buffers.

The recommended way to size these settings is the top-level presets.cpu and presets.ram values, which override a fixed table of settings.engine fields at render time. For finer control, set settings.engine directly instead—see Manual Tuning below.

Sizing Presets#

presets.cpu and presets.ram are optional, unset (~) by default. Each is a closed enum validated by the chart’s schema, so an unsupported value is rejected before the chart renders rather than silently ignored. Leaving both unset uses settings.engine exactly as written.

presets:
  cpu: 8       # One of 1, 2, 3, 4, 5, 6, 7, 8.
  ram: "48GB"  # One of 4GB, 6GB, 7GB, 8GB, 12GB, 16GB, 24GB, 32GB, 48GB, 64GB.

presets.cpu overrides settings.engine.increaseParallelism / threadsHigh / threadsLow:

`presets.cpu`	`increaseParallelism`	`threadsHigh`	`threadsLow`
`1`	1	1	1
`2`	2	1	1
`3`	3	2	1
`4`	4	2	2
`5`	5	3	2
`6`	6	3	3
`7`	7	4	3
`8`	8	4	4

presets.ram overrides settings.engine.cacheSize / blockCacheSize, and settings.engine.blobsCf.max_write_buffer_number:

`presets.ram`	`cacheSize`	`b lockCacheSize`	`blo bsCf.max_write_ buffer_number`
`4GB`	1G	3G	24
`6GB`	2G	4G	32
`7GB`	3G	4G	32
`8GB`	4G	4G	32
`12GB`	7G	5G	32
`16GB`	10G	6G	32
`24GB`	16G	8G	32
`32GB`	22G	10G	32
`48GB`	36G	12G	32
`64GB`	52G	12G	32

settings.engine.cf.max_write_buffer_number (the default column family, holding keys and small values) is not affected by either preset—it stays at whatever settings.engine.cf is written (4 by default).

resources.requests.memory should cover cacheSize + blockCacheSize (from the table above) plus roughly 6GB of TCP buffers. Write buffers for both column families (cf and blobsCf) share the block cache budget when settings.engine.useWriteBufferManager is true (the default), so they are already covered by blockCacheSize and should not be added a second time. For example, presets.ram: "48GB" gives 36G + 12G + 6G ≈ 54G, close to the chart’s default resources.requests.memory of 56G.

If settings.engine.useWriteBufferManager is set to false, write buffers are no longer charged against blockCacheSize and must be added on top instead: cf’s 64M x 4 ≈ 256M plus blobsCf’s 64M times the blobsCf.max_write_buffer_number value from the table above.

Manual Tuning#

Leave presets.cpu / presets.ram unset to tune settings.engine directly instead. The fields below are the ones the presets tables above cover; the RocksDB db / cf / block / blobsCf / blobsBlock option maps are always read from settings.engine regardless of presets—see the full values reference.

Row Cache (settings.engine.cacheSize): OVDC’s own in-process cache holding recently read entries, not a RocksDB cache. Defaults to 32G. 0 disables it.
Block Cache (settings.engine.blockCacheSize): RocksDB’s LRU block cache for metadata, filters, and file blocks. Defaults to 8G. Also backs the write buffer manager when settings.engine.useWriteBufferManager is true (the default), so the two share one memory budget instead of adding up.
Write Buffers (settings.engine.cf.* and settings.engine.blobsCf.* write_buffer_size x max_write_buffer_number): In-memory buffers that absorb write bursts before flushing to disk. There are two independent pools, one per column family. cf (the default CF) defaults to a 64MB buffer size with 4 buffers (~256MB); blobsCf (the blob-file CF, which holds most user-write data under the default store.mode: "log") defaults to a 64MB buffer size with 24 buffers (~1.5GB)—roughly 1.75GB combined. When useWriteBufferManager is true (the default), this memory is charged against blockCacheSize rather than adding to it—see resources.requests.memory below. Set useWriteBufferManager to false to make write buffers a separate, additive memory pool instead.

3. Volume Configuration#

Reading from persistent storage, even a network-attached volume, is often faster than regenerating derived data. Therefore, OVDC persists content to a Kubernetes volume.

storage:
  volume:
    size: 330Gi
    storageClassName: "gp3"

storage.volume.size determines the size of the PersistentVolumeClaim created and attached to each pod. volumeClaimTemplates are immutable, so changing this value on an existing release is rejected on upgrade—plan the size up front.

storage.volume.storageClassName determines the performance characteristics of the persistent volume. Select a storage class that provides high IOPS and throughput suitable for database workloads (see the 800 MB/s guidance above).

settings.store.maxSize is the RocksDB on-disk target and the denominator garbage collection measures free capacity against. The default is "AUTO", which derives the target from storage.volume.size: the whole volume less min(20%, 100GB) of headroom.

Volume	Resulting target
10Gi	80.0%
300Gi	80.0%
1Ti	90.9%
10Ti	99.1%

AUTO requires storage.volume.enabled: true; the render fails otherwise. To set an explicit size instead, use a value such as "275G", which is used verbatim.

Example Kubernetes StorageClass for AWS#

If a StorageClass named gp3 does not already exist in your cluster, one can be created using the following configuration:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gp3
provisioner: kubernetes.io/aws-ebs
volumeBindingMode: WaitForFirstConsumer
parameters:
  type: gp3
  iops: "5000"
  throughput: "1000"

Apply this StorageClass to your cluster:

kubectl apply -f storageclass-gp3.yaml

4. Telemetry#

OVDC exposes Prometheus metrics for monitoring cache performance, hit rates, and storage utilization, and can separately export traces, logs, and metrics through OpenTelemetry (OTLP over gRPC, the same remote-procedure-call protocol OVDC’s client API itself uses).

settings:
  telemetry:
    prometheusMetricsExposition: true
    prometheusMetricsPort: 3051

Metrics Configuration:

settings.telemetry.prometheusMetricsExposition: When true, an HTTP metrics service is started on prometheusMetricsPort, serving Prometheus plain-text metrics. When false, nothing listens on the port, but the Service and its scrape annotations are still created, so scrapes fail rather than being skipped.
prometheusAnnotation (top level): When true, adds prometheus.io/* scrape annotations to the metrics Service.

OTLP export is separate and requires a collector you provide—the chart does not deploy one. Configure it under settings.otelTraces, settings.otelLogs, and settings.otelMetrics, each with its own exporter ("otlp" or "none") and otlp.endpoint. This build only ships the gRPC OTLP exporter; http/protobuf and http/json deserialize but export nothing.

Note

There is no ServiceMonitor in this chart, and the standalone OTel-collector sidecar (otelCollector.*) was removed in 6.0.0. Run a collector separately and point the otel*.otlp.endpoint settings at it, or use the prometheus.io/* annotations with a Prometheus that supports annotation-based scraping.

Configuration Recommendations#

The following configurations provide complete values files for different cluster sizes. Each configuration includes all base settings; only replicas changes between tiers, following the compute-node-count math from Provision and Scale above. Adjust resources.requests.memory and storage.volume.size for your actual workload.

1-5 GPU

image:
  pullSecrets:

    - name: regcred

replicas: 2  # 2 compute nodes x 12.5 Gbps NIC = 25 Gbps capacity
selfAntiAffinity: true
affinity:
  nodeAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:

      - weight: 100
        preference:
          matchExpressions:

            - key: node-type
              operator: In
              values:

                - compute

resources:
  requests:
    memory: 56G

storage:
  volume:
    size: 330Gi
    storageClassName: "gp3"

presets:
  cpu: 8
  ram: "48GB"

settings:
  logFormat: "json"
  logLevel: "info"
  store:
    maxSize: AUTO
  telemetry:
    prometheusMetricsExposition: true
    prometheusMetricsPort: 3051

5-10 GPU

image:
  pullSecrets:

    - name: regcred

replicas: 3  # 3 compute nodes x 12.5 Gbps NIC = 37.5 Gbps capacity
selfAntiAffinity: true
affinity:
  nodeAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:

      - weight: 100
        preference:
          matchExpressions:

            - key: node-type
              operator: In
              values:

                - compute

resources:
  requests:
    memory: 56G

storage:
  volume:
    size: 330Gi
    storageClassName: "gp3"

presets:
  cpu: 8
  ram: "48GB"

settings:
  logFormat: "json"
  logLevel: "info"
  store:
    maxSize: AUTO
  telemetry:
    prometheusMetricsExposition: true
    prometheusMetricsPort: 3051

10-25 GPU

image:
  pullSecrets:

    - name: regcred

replicas: 6  # 6 compute nodes x 12.5 Gbps NIC = 75 Gbps capacity
selfAntiAffinity: true
affinity:
  nodeAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:

      - weight: 100
        preference:
          matchExpressions:

            - key: node-type
              operator: In
              values:

                - compute

resources:
  requests:
    memory: 56G

storage:
  volume:
    size: 330Gi
    storageClassName: "gp3"

presets:
  cpu: 8
  ram: "48GB"

settings:
  logFormat: "json"
  logLevel: "info"
  store:
    maxSize: AUTO
  telemetry:
    prometheusMetricsExposition: true
    prometheusMetricsPort: 3051

Summary#

This guide covered the configuration options for OVDC, including scaling considerations, memory allocation, storage sizing, and monitoring setup. Proper configuration of these settings is essential for optimal OVDC performance in your self-hosted NVCF cluster.

Once you have prepared your values.yaml file with the appropriate configuration, proceed to the deployment guide to deploy OVDC using Helm.