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 |
|---|---|---|---|---|
|
boolean |
No |
|
Requires
TLS on the
gRPC
listener
when
|
|
string |
Yes, when
|
|
Name of the
Kubernetes
TLS Secret
to mount.
The render
fails if
|
|
boolean |
No |
|
When
|
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.