OVDC: TLS Configuration#

This guide covers enabling TLS encryption for inter-cluster cache communication.

Note

In-cluster transport is plaintext by default (settings.grpcTls.enabled: false). This is a deliberate default—a workload Helm chart cannot mint certificates for itself at install time, so in-cluster service-to-service encryption is typically provided by a service mesh or operator-issued certificates. TLS support exists and can be switched on with an operator-supplied Secret, as covered below.

1. Create the TLS Secret#

Create a Kubernetes TLS secret with your certificate and key:

kubectl create secret tls ovdc-tls \
   --cert=tls.crt \
   --key=tls.key \
   --namespace ovdc

Important

The DNS names clients connect to MUST be included in the certificate’s DNS Subject Alternative Names (SANs); a Common Name alone is insufficient. With release ovdc in namespace ovdc, pod 0 is ovdc-ovderivedcache-0.ovdc-ovderivedcache.ovdc.svc.cluster.local. Include each required pod name or the wildcard *.ovdc-ovderivedcache.ovdc.svc.cluster.local. If clients also use the Service FQDN, include ovdc-ovderivedcache.ovdc.svc.cluster.local separately.

Self-Signed Certificate (Reference Only)#

For testing purposes only, you can create a self-signed certificate using OpenSSL. This example assumes release ovdc and namespace ovdc; adjust both DNS SANs for your deployment:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
   -keyout tls.key -out tls.crt \
   -subj "/CN=ovdc-ovderivedcache.ovdc.svc.cluster.local" \
   -addext "subjectAltName=DNS:*.ovdc-ovderivedcache.ovdc.svc.cluster.local,DNS:ovdc-ovderivedcache.ovdc.svc.cluster.local"

Warning

Self-signed certificates should NOT be used in production environments. Use certificates from a trusted Certificate Authority (CA) for production deployments.

2. Enable TLS in values.yaml#

After creating the TLS secret, enable TLS in your values.yaml file under settings.grpcTls. Unlike other gRPC settings, the certificate and key paths are fixed by the chart at /etc/ovdc/tls and are not configurable—only the Secret name is.

settings:
  grpcTls:
    # Require TLS on the gRPC listener.
    enabled: true
    # Name of the Kubernetes TLS secret created in step 1.
    secretName: ovdc-tls

The chart mounts the named Secret read-only at /etc/ovdc/tls and points the application at /etc/ovdc/tls/tls.crt and /etc/ovdc/tls/tls.key. secretName is required when enabled is true; the render fails otherwise. This section of settings is read once at startup, so changing it requires a pod restart.

TLS Handshake Timeout#

settings.grpc.tlsHandshakeTimeout limits the time allowed to complete each TLS handshake. It defaults to "10s" and must be positive. When the deadline expires, OVDC closes the socket and increments ovdc_api_tls_handshake_timeout_total. The timeout is read at startup; changing it requires a pod restart.

settings:
  grpc:
    tlsHandshakeTimeout: "10s"

settings.grpcTls Field Reference#

Field

Type

Required

Default

Description

enabled

boolean

No

false

Requires TLS on the gRPC listener when true. Plaintext by default—see the note at the top of this guide.

s ecretName

string

Yes, when enab led: true

""

Name of the Kubernetes TLS Secret to mount. The render fails if enabled is true and this is empty.

incl udeCaRoot

boolean

No

false

When true, also mounts ca.crt from the same Secret and uses it as the CA root. See Configure CA Root Cer tificate below.

3. Optional: Configure CA Root Certificate#

If your deployment requires a custom CA root certificate for validation, enable includeCaRoot. The Secret must then also carry a ca.crt key, which kubectl create secret tls does not add on its own. Use the command below instead of the Secret creation command in step 1. If ovdc-tls already exists, the dry-run-and-apply form updates it to include all three files while preserving the existing kubernetes.io/tls Secret type:

kubectl create secret generic ovdc-tls -n ovdc \
  --type=kubernetes.io/tls \
  --from-file=tls.crt=cert.pem \
  --from-file=tls.key=key.pem \
  --from-file=ca.crt=ca.pem \
  --dry-run=client -o yaml | kubectl apply -f -
settings:
  grpcTls:
    enabled: true
    secretName: ovdc-tls
    includeCaRoot: true

When includeCaRoot is true, the application reads /etc/ovdc/tls/ca.crt as the CA root.

4. Complete Example Configuration#

Here is a complete example showing TLS configuration within a typical OVDC values.yaml:

image:
  pullSecrets:

    - name: regcred

replicas: 1
resources:
  requests:
    memory: 56G
storage:
  volume:
    size: 330Gi
    storageClassName: "gp3"

settings:
  store:
    maxSize: AUTO
  engine:
    cacheSize: "32G"
    blockCacheSize: "8G"
  grpcTls:
    enabled: true
    secretName: ovdc-tls

5. Apply Configuration Changes#

After updating your values.yaml file with TLS configuration, apply the changes using Helm:

helm upgrade ovdc omniverse/ovderivedcache \
    --version 6.0.3 \
    --namespace ovdc \
    -f values.yaml

If you are installing OVDC for the first time with TLS enabled:

helm install ovdc omniverse/ovderivedcache \
    --version 6.0.3 \
    --namespace ovdc \
    -f values.yaml

6. Verify TLS Configuration#

After applying the configuration, verify that TLS is enabled:

# Check that the TLS secret is mounted in the pod
kubectl describe pod -n ovdc -l app.kubernetes.io/instance=ovdc | grep -A 5 "Mounts:"

# Verify the pod is running successfully
kubectl get pods -n ovdc -l app.kubernetes.io/instance=ovdc

The TLS secret should be mounted at /etc/ovdc/tls and the pod should be healthy. The chart’s readiness probe checks only TCP connectivity, so also verify TLS from a client. Run this port-forward in a separate terminal (adjust the pod name for your release):

kubectl port-forward -n ovdc pod/ovdc-ovderivedcache-0 3010:3010

Use OpenSSL 3.x (openssl version), rather than the LibreSSL bundled with some macOS versions, for the hostname verification command below. With the issuing CA certificate ca.pem on your workstation, verify the certificate chain and the pod’s DNS identity. For the self-signed test example, use tls.crt as the CA file instead. -verify_hostname checks the real pod DNS name even though the connection is forwarded through localhost:

openssl s_client -connect localhost:3010 \
  -servername ovdc-ovderivedcache-0.ovdc-ovderivedcache.ovdc.svc.cluster.local \
  -verify_hostname ovdc-ovderivedcache-0.ovdc-ovderivedcache.ovdc.svc.cluster.local \
  -CAfile ca.pem -verify_return_error -alpn h2 </dev/null

Expect a successful handshake and Verify return code: 0 (ok). A failed chain or hostname check must be corrected before relying on the connection.

With grpcurl installed, also try a plaintext gRPC request against the same forwarded listener:

grpcurl -plaintext -connect-timeout 5 -max-time 10 localhost:3010 list

Expect a transport/connection failure because the listener requires TLS. A successful RPC or a gRPC response such as “server does not support the reflection API” means plaintext reached the application and is not an acceptable result. A bare TCP connection can still succeed on a TLS listener; it does not prove that plaintext gRPC is accepted.

Summary#

For deployment instructions, refer to the deployment guide. For general configuration options, refer to the configuration guide.