UCC: Configure#

This guide provides detailed information on the USD Content Cache (UCC) component and its use in a self-hosted NVCF cluster.

UCC provides a content store running as an intermediary between object storage and Cloud Function clients. It caches USD (Universal Scene Description) content to accelerate scene loading and reduce bandwidth usage. UCC acts as a reverse proxy cache, intercepting requests for USD content from object storage sources like S3, Azure Blob Storage, or NVIDIA Omniverse Nucleus, and serving cached content when available.

Cached content reduces egress costs from cloud storage providers and improves scene load times. When content is requested, UCC first checks its local cache. On a cache hit, content is served directly from persistent storage. On a cache miss, UCC fetches the content from the upstream source, caches it locally, and serves it to the requesting client.

Base Configuration#

UCC 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.

replicaCount: 3

image:
  pullSecrets:

    - name: ngc-container-pull

persistence:
  storageClassName: "gp3"
  volumes:

    - name: az
      path: /proxy_cache_az
      sizeGi: 256
      minFreeSizePercentage: 7

    - name: s3
      path: /proxy_cache_s3
      sizeGi: 256
      minFreeSizePercentage: 7

    - name: nucleus
      path: /proxy_cache_nucleus
      sizeGi: 256
      minFreeSizePercentage: 7

nginx:
  proxyCache:
    validity:
      "200": "1d"
      "206": "1d"
  backends:
    azure:
      include: true
      cacheTtl: 30
    s3:
      include: true
      cacheTtl: 30

metrics:
  prometheus:
    enabled: true
    serviceMonitor:
      enabled: false

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 UCC Helm chart, including advanced settings for TLS, OpenTelemetry, and resource management.

# See samples/configs/ucc_values_full.yaml for complete reference

1. Provision and Scale#

UCC replicas operate independently of each other and do not share cached data. Each pod maintains its own cache and distributes requests from clients. Multiple replicas provide high availability and can handle higher request volumes.

Important

UCC is not designed to scale up and down dynamically. Set the replica count based on your expected workload and maintain it consistently.

The number of UCC pods is controlled through the replicaCount value:

replicaCount: 3

Recommended Replica Counts:

  • Small deployments: 1-2 replicas

  • Typical deployments: 3 replicas (recommended baseline)

  • Large deployments: 3-5 replicas

2. Storage Configuration#

UCC uses persistent volumes to cache USD content from upstream sources. Each configured backend (Azure Blob, S3, Nucleus) has its own persistent volume. Storage performance directly impacts cache hit performance and the speed at which cold assets can be served.

persistence:
  storageClassName: "gp3"
  volumes:

    - name: az
      path: /proxy_cache_az
      sizeGi: 256
      minFreeSizePercentage: 7

    - name: s3
      path: /proxy_cache_s3
      sizeGi: 256
      minFreeSizePercentage: 7

    - name: nucleus
      path: /proxy_cache_nucleus
      sizeGi: 256
      minFreeSizePercentage: 7

storageClassName determines the performance characteristics of persistent volumes. Select a storage class that provides high IOPS and throughput suitable for cache workloads.

Storage Class Recommendations:

  • AWS (EKS): gp3 (recommended) or io1/io2 for higher performance

  • Azure (AKS): managed-csi-premium

  • On-Premises: Select a storage class backed by high-performance hardware

sizeGi determines the volume size for each cache backend. Plan cache size based on your workload:

  • Small workloads: 50-100GB per provider

  • Medium workloads: 100-500GB per provider

  • Large workloads: 500GB+ per provider

minFreeSizePercentage restricts cached content size by maintaining a minimum number of free bytes. The default value of 7 means the service will restrict cached content to 93% of the available capacity, leaving 7% free space for filesystem operations and preventing disk exhaustion.

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

3. Cache Configuration#

UCC cache behavior is controlled through NGINX proxy cache settings. These settings determine how long content is cached, how cache metadata is stored, and when cached content expires.

nginx:
  proxyCache:
    validity:
      "200": "1d"
      "206": "1d"
  backends:
    azure:
      include: true
      cacheTtl: 30
    s3:
      include: true
      cacheTtl: 30

Cache Validity (validity): Controls how long content is cached based on HTTP status codes. When the upstream source returns the specified HTTP status code, the result is kept for the given time period. Default values cache successful responses (200, 206) for 1 day.

Backend Configuration: UCC supports multiple upstream backends. Each backend can be enabled or disabled, and has specific routing rules:

  • Azure Blob (azure): Matches Azure Blob Storage URLs using regex pattern

  • S3 (s3): Matches Amazon S3 URLs using regex pattern

  • Nucleus (nucleus): Default backend that catches any hostname not matched by other servers

Each backend configuration includes:

  • include: Enable or disable the backend

  • cacheTtl: Cache time-to-live in seconds

5. Telemetry#

UCC exports Prometheus metrics for monitoring cache performance, hit rates, and storage utilization. Collection of these metrics is important for diagnosing potential problems with UCC performance and optimizing cache configuration.

metrics:
  prometheus:
    enabled: true
    serviceMonitor:
      enabled: false

Metrics Configuration:

  • prometheus.enabled: When true, creates a Kubernetes service that exports metrics in Prometheus format at /cache_metrics

  • prometheus.serviceMonitor.enabled: When true, creates a ServiceMonitor resource for Prometheus Operator integration

Important

The ServiceMonitor CRD must be installed in the cluster for ServiceMonitor resources to work.

Summary#

This guide covered the configuration options for UCC, including replica scaling, storage sizing, memory allocation, cache behavior, and monitoring setup. Proper configuration of these settings is essential for optimal UCC 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 UCC using Helm.

For TLS configuration instructions, refer to the TLS guide.