Live Edit Service configuration#

Goal: Deploy Live Edit with a durable backing store and authenticated access for collaborating clients. This guide covers first installation using the 0.1.1 Helm chart and container. Complete the prerequisites and choose a durability mode before installing.

Service ports#

Port	Protocol	Purpose
50001	gRPC over HTTP/2	Live Edit API, health checks and Discovery capabilities
9090	HTTP	Prometheus `/metrics`

The service accepts plaintext gRPC inside the cluster. Terminate client TLS at an HTTP/2-capable ingress or gateway, and restrict direct access to the service and metrics ports.

Prerequisites#

Prepare the following before installing:

Kubernetes with Helm and kubectl, support for gRPC probes, and permission to pull the supplied NGC artifacts.
A Valkey-compatible deployment meeting the backing-store requirements. Use a separate keyspace for each independent Live Edit deployment.
An authenticated Storage Service and existing base assets accessible through it. The examples use the Storage REST endpoint; it must support HEAD /v1alpha/fileobject/by-address/{address} and validate callers’ bearer tokens.
A client identity accepted by that Storage Service. When User Info is disabled, identity-resolving requests require a JWT with a nonempty name, preferred_username, sub or oid claim.
If using external checkpoints, a registered storage location, a service identity with read/list/write/delete access to a dedicated backup prefix, and a renewable token provider for that identity.

The Storage endpoint, base asset address and checkpoint prefix are different settings. For example, the endpoint can be https://storage.example.com, a base asset can be https://assets.example.com/project/scene.usd, and the checkpoint prefix can be https://assets.example.com/live-edit-backups/. Use addresses registered with your Storage Service, not an arbitrary local filesystem path.

Authentication and access#

Keep authorization.enabled: true for path-level access checks. Authentication cannot be disabled. Live Edit forwards callers’ tokens to Storage to check access to the base resource; it does not call the Permission Service directly. Storage must enforce token validation and the access policies required by your deployment.

Important

In this release, both read and modifying Live Edit operations use Storage’s read/stat access check. A caller allowed to read/stat the base asset can also modify its live sessions and layers. Do not rely on Storage read-versus-write permissions to provide a read-only Live Edit participant role.

For external identity resolution, or for opaque bearer tokens, configure User Info before installation:

userInfo:
  enabled: true
  endpoint: "https://userinfo.example.com"

authorization.protocol selects REST or gRPC for both Storage and User Info calls. The examples use REST; use the corresponding gRPC endpoints if changing the protocol. Disabling both path authorization and User Info is rejected at startup. Enabling User Info alone does not enforce access to base assets.

Pull the Helm chart#

Use an NGC API key authorized for the chart and container:

export LIVE_EDIT_VERSION=0.1.1
helm fetch "https://helm.ngc.nvidia.com/nvidia/omniverse/charts/live-edit-service-${LIVE_EDIT_VERSION}.tgz" \
  --username='$oauthtoken' --password="${NGC_API_KEY}"
tar -xvf "live-edit-service-${LIVE_EDIT_VERSION}.tgz"
cd live-edit-service

Run the following chart commands from this extracted directory. Create namespace storage-apis if it does not already exist, or substitute your namespace throughout. Create the image-pull Secret there if you do not already have it:

kubectl create namespace storage-apis
kubectl create secret docker-registry ngcpull-secret \
  --docker-server=nvcr.io --docker-username='$oauthtoken' \
  --docker-password="${NGC_API_KEY}" --namespace storage-apis

Configure the backing-store connection#

For password or ACL authentication, store the full Valkey URL in a Kubernetes Secret named live-edit-env, under key valkey-url. Use your secret manager or create it from an environment variable containing the credential-bearing URL:

kubectl create secret generic live-edit-env \
  --from-literal=valkey-url="${LIVE_EDIT_VALKEY_URL}" \
  --namespace storage-apis

Use rediss:// for a TLS connection to a single primary endpoint or rediss-cluster:// for a TLS cluster endpoint. URL-encode reserved characters in embedded credentials. Do not put credential-bearing URLs in Helm values. See Backing-store authentication for passwordless alternatives.

Choose durability#

Valkey persistence and Live Edit checkpoints address different failure cases. Persistent Valkey protects live state across the failures covered by your backing-store deployment. Independent checkpoints can recover saved live state after loss of that store. For production recovery from complete Valkey loss, use both.

The chart defaults to checkpoint.enabled: true and checkpoint.adapter: Disabled. That combination refuses startup: you must select a real adapter or explicitly disable checkpoints.

Rely on backing-store durability#

The basic values below disable external checkpoints and rely on a persistent backing store. For self-hosted Valkey, enable AOF and persistent volumes first. For a managed store, confirm its durability configuration with the provider.

Warning

With checkpoints disabled, loss of the complete Valkey dataset also loses Live Edit sessions and layer state. Use external checkpoints if your recovery requirements include that failure case. A successful startup does not verify a managed provider’s durability guarantees.

Create live-edit-values.yaml:

image:
  repository: nvcr.io/nvidia/omniverse/live-edit-service
  tag: "0.1.1"
  pullSecrets:
    - name: ngcpull-secret

envSecretName: live-edit-env

authorization:
  enabled: true
  protocol: rest
  storageServiceEndpoint: "https://storage.example.com"

userInfo:
  enabled: false

checkpoint:
  enabled: false
  adapter: Disabled

Replace storageServiceEndpoint with your authenticated Storage REST endpoint. The chart’s default three replicas, autoscaler and disruption budget remain enabled. If you require external checkpoints, merge the next configuration into this file before installation. Do not create duplicate top-level YAML keys.

Add external checkpoints#

Use the StorageApi adapter for a shared backup store accessible to all replicas:

checkpoint:
  enabled: true
  adapter: StorageApi
  storageApiEndpoint: "https://storage.example.com"
  basePath: "https://assets.example.com/live-edit-backups/"
  credentials:
    accessTokenFile:
      path: /etc/secrets/access-token/access_token
      pollIntervalSecs: 15

serviceIdentity:
  accessTokenFile:
    enabled: true
    provisionerSidecar:
      container:
        image: "YOUR_TOKEN_PROVISIONER_IMAGE:VERSION"
        # Add the environment/arguments required by your token provider.

Replace the token-provisioner placeholder with your configured credential container before deploying. The chart supplies its name and a shared writable mount at /etc/secrets/access-token; the Live Edit container reads that mount read-only. Configure the provider to obtain a token for the Storage API audience, refresh it before expiry, and atomically write this JSON file at the configured path:

{"access_token": "TOKEN_VALUE", "expires_on": "2030-01-01T00:00:00Z"}

expires_on must be the token’s actual expiry in RFC 3339 form, not the example date. The outbound service identity is separate from each collaborating user’s identity. serviceIdentity.clientCredentials.enabled does not acquire tokens in this release; use the token-file provider.

The backup prefix must be dedicated to this Live Edit deployment. Allow network access to both the Storage endpoint and any object-storage destinations it returns for uploads or downloads. See Recovery and backup validation before relying on checkpoints.

Configure ingress and network access#

The chart can create a Contour HTTPProxy when Contour is installed. Provide a DNS name and an existing TLS Secret, or configure the chart’s certificate-manager integration:

httpProxy:
  enabled: true
  fqdn:
    host: live-edit
    domain: example.com
  tls:
    enabled: true
    secretName: live-edit-tls

Keep HTTP/2 routing to port 50001. The chart gives JoinSession and SubscribeReadLayer response and idle timeouts of 240 minutes. Other routes, including client-streaming layer uploads, use httpProxy.timeoutPolicy with 30-second defaults. Adjust upload timeouts for your workloads; clients must reconnect when long-lived streams end. No session affinity is required.

Network rules must allow DNS, the actual Valkey nodes and ports, Storage, optional User Info, token-provider endpoints, backup transfer destinations and any telemetry collector. The optional built-in networkPolicy is disabled by default and does not cover every deployment’s dependency ports, including the usual Storage REST port 8012. Review or supply policies for your endpoints before enabling restrictions.

Install and validate#

Validate and install using your completed values:

helm lint . -f live-edit-values.yaml
helm upgrade --install live-edit-service . \
  --namespace storage-apis -f live-edit-values.yaml
kubectl rollout status deployment/live-edit-service -n storage-apis
kubectl logs deployment/live-edit-service -n storage-apis -c live-edit-service --tail=100

Preserve the chart’s gRPC startup, readiness and liveness probes. Readiness uses nvidia.omniverse.live.v1alpha.LiveService; the empty health-service name is liveness only. Readiness checks startup progress, Valkey and configured service-token availability, but does not verify all authorization or backup operations. Use authenticated tests as well.

Run authenticated smoke tests#

The chart’s smoke tests create and delete a disposable Storage fixture and a live session. Use a dedicated test location and a principal allowed to create/read/delete the fixture and operate the session. These tests use the Storage REST endpoint from authorization.storageServiceEndpoint.

Create the OAuth Secret before enabling tests:

kubectl create secret generic live-edit-smoke-auth \
  --from-literal=credentials="${TEST_CLIENT_ID}:${TEST_CLIENT_SECRET}" \
  --namespace storage-apis

Merge into live-edit-values.yaml, replacing the identity-provider and storage placeholders:

smokeTest:
  image:
    pullSecrets:
      - name: ngcpull-secret

tests:
  enabled: true
  storageApiResourceBase: "https://assets.example.com/live-edit-tests/"
  auth:
    microsoftUrl:
      value: "https://login.microsoftonline.com/TENANT_ID/v2.0/.well-known/openid-configuration"
    credentials:
      valueFrom:
        secretKeyRef:
          name: live-edit-smoke-auth
          key: credentials
    scope:
      value: "STORAGE_API_AUDIENCE/.default"

microsoftUrl is an OIDC discovery-document URL, not a token endpoint. The tests run on install/upgrade when enabled, and can also be invoked explicitly:

helm upgrade live-edit-service . --namespace storage-apis -f live-edit-values.yaml
helm test live-edit-service --namespace storage-apis --logs

Before production use, also connect two compatible Live Edit clients to a disposable base asset, join the same session, publish a layer edit and verify the other client receives it. The smoke suite does not exercise actual layer-content editing. If checkpoints are enabled, verify successful backup and recovery separately.

Register with Discovery#

When a Discovery operator is installed, opt the Kubernetes Service into registration:

service:
  annotations:
    discovery.omniverse.nvidia.com/enabled: "true"

The service advertises the live-service service type and its gRPC API through the capabilities endpoint. If using a static Discovery configuration, register the externally reachable gRPC endpoint using the matching Live Edit client configuration. Continue with Operations for monitoring, scaling and updates.