NVIDIA Minerva's platform tier presents a TLS certificate on the web UI (port 443). This procedure replaces that certificate with a customer-provided one (for example, a certificate signed by a public Certificate Authority).
Important — this is a shared platform certificate. The same certificate (server.crt / server.key) is presented on both the UI and the platform's OTLP mTLS ingestion endpoint (port 14317) that collectors connect to, and it backs several other backend services. Replacing it affects collector-to-platform ingestion on hybrid deployments, and a full stack-down all / stack-up all is required — this is not a UI-only change. On unified and platform-only deployments with no separate collector, only the platform steps apply.
Before You Begin
Confirm that the new certificate meets the following requirements:
-
Full chain.
server.crtmust contain the server (leaf) certificate followed by any intermediate CA certificates, concatenated in one PEM file (leaf first). Certificates from public CAs almost always require intermediates; a leaf-only file means the collector cannot build a trust path even if the root is trusted. -
Subject Alternative Name (SAN). The certificate's SAN must cover the platform FQDN. On a hybrid deployment this must be the exact FQDN that collectors use to reach the platform (the OTLP ingestion endpoint), not only the browser-facing UI hostname. The collector performs hostname/SAN verification on the server cert, so a mismatch silently breaks ingestion.
-
Matching key.
server.keymust be the private key forserver.crt.
Find the Collector-Facing FQDN (Hybrid)
The SAN must match this value. On a collector node, read it from the running gateway-push service:
docker service inspect backend_otelcol-gateway-push \
--format '{{range .Spec.TaskTemplate.ContainerSpec.Env}}{{println .}}{{end}}' \
| grep -E 'PROCESSOR_ADDR|CONFIG_EXTERNAL_URL'
Use that hostname (for example, ip-172-31-31-80.us-west-2.compute.internal) in the leaf SAN, not the public UI hostname unless they are the same.
Validate the Certificate
# 1) The certificate chains to its CA.
# Provide intermediates via -untrusted (or put root+intermediates in the CAfile);
# -CAfile with the root ALONE fails for a real public-CA leaf ("unable to get local issuer").
openssl verify -CAfile root.crt -untrusted intermediate.crt server_leaf.crt
# (leaf-only file; if server.crt is the full leaf+intermediate bundle, verify the leaf separately)
# 2) The certificate and key match (the two hashes must be identical).
# Use `pkey` (algorithm-agnostic) — `openssl rsa` fails on ECDSA/Ed25519 keys.
openssl x509 -noout -pubkey -in server.crt | openssl md5
openssl pkey -pubout -in server.key | openssl md5
# 3) The SAN covers the required FQDN(s):
openssl x509 -noout -text -in server.crt | grep -A1 "Subject Alternative Name"
Steps by Deployment Type
|
Deployment |
Steps |
|---|---|
|
Unified / platform-only |
Step 2 only |
|
Hybrid |
Step 1 on all collectors, then Step 2 on the platform |
Complete Step 1 on all collectors before starting Step 2. Appending the new CA to a collector's trust store is harmless while the old cert is still in use — the collector simply trusts both CAs. If you replace the platform cert first, every collector rejects it with x509: certificate signed by unknown authority and ingestion stops until you finish updating every collector's trust store. Pre-staging trust makes the platform cutover seamless.
Step 1: Update Collector Trust Stores (Hybrid Only)
On a hybrid deployment, the collector verifies the platform's certificate against a pinned CA file (~/minerva/secrets/ca-certs/root-ca.crt), not against the OS or public-CA trust store. If the new certificate is signed by a different CA (for example, a public CA), you must add that CA to the collector's trust store, or ingestion will stop.
Run the following on each collector node:
cd ~/minerva
# 1. Stop the stack
./svm stack-down all
# 2. Back up, then append the new root CA to the trust bundle (do not replace the file)
cp -a secrets/ca-certs/root-ca.crt ~/cert-backup-collector-root-ca.crt
cat /path/to/publicRootCA.crt >> secrets/ca-certs/root-ca.crt
# 3. Rebuild the secrets and start the stack
./svm secrets
./svm stack-up all
Use cat >> to append the new root CA to the existing bundle. Do not overwrite the file, and do not add a separate file — nginx and otel reference ca-certs/root-ca.crt by exact name, so a separate file becomes an unmounted secret and is silently ignored. Append only the root CA, not the leaf or intermediate. The bundle must keep the original NVIDIA Minerva CA so the collector's own client identity to the platform remains valid.
Step 2: Replace the Platform Certificate (All Deployments)
Run the following commands on the NVIDIA Minerva platform (or unified) manager node:
cd ~/minerva
# 1. Back up current secrets (kept outside the secrets folder)
./svm secrets-backup
mkdir -p ~/cert-backup
cp -a secrets/server.crt secrets/server.key ~/cert-backup/
# 2. Stop the stack
./svm stack-down all
# 3. Install the new certificate and key
# (server.crt must be the FULL chain: leaf + intermediates, leaf first)
install -m644 /path/to/server.crt secrets/server.crt
install -m600 /path/to/server.key secrets/server.key
# 4. Rebuild the certificate secrets from the new files <-- required step
./svm secrets
# 5. Start the stack
./svm stack-up all
Do not skip step 4. ./svm stack-up does not re-read the certificate files — it redeploys using the stored secrets. ./svm secrets is what loads the new files into NVIDIA Minerva. (Confirmed: the served cert only changes after ./svm secrets.)
Do not replace secrets/ca-certs/root-ca.crt on the platform. That file controls which collectors are trusted for ingestion (it validates the collector's client cert); leaving it unchanged keeps existing collectors working.
Keep all backups outside ~/minerva/secrets/. Any extra file left in that folder is turned into an NVIDIA Minerva secret on the next ./svm secrets.
Verification
# Platform: the UI now serves the new certificate (issuer should be your CA)
echo | openssl s_client -connect <platform-fqdn>:443 -servername <platform-fqdn> 2>/dev/null \
| openssl x509 -noout -issuer -subject -dates
# Platform: the OTLP mTLS ingest endpoint serves the same new cert
echo | openssl s_client -connect <platform-fqdn>:14317 -servername <platform-fqdn> 2>/dev/null \
| openssl x509 -noout -issuer -subject
# Hybrid: confirm collector→platform ingestion is healthy (no cert/TLS errors).
# The CA-mismatch failure is a gRPC/TLS handshake error, NOT an HTTP 400 — grep accordingly.
docker service logs backend_otelcol-gateway-push --since 5m \
| grep -iE "x509|unknown authority|handshake failed|failed to verify certificate|tls|Exporting failed" \
|| echo "no TLS/export errors"
The expected result is: openssl s_client shows your issuer on both :443 and :14317, and the gateway-push log grep returns empty. The failure signature this procedure prevents is:
rpc error: ... authentication handshake failed:
tls: failed to verify certificate: x509: certificate signed by unknown authority
After a hybrid change, also confirm in the NVIDIA Minerva UI (or via Druid) that data from the collector is current — recent timestamps advancing on the affected data sources — not just that services are up.
Rollback
Restore the previous certificate from your backup, then rerun the load-and-restart steps.
Platform:
cd ~/minerva
./svm stack-down all
cp -a ~/cert-backup/server.crt ~/cert-backup/server.key secrets/
./svm secrets
./svm stack-up all
Collector (hybrid): restoring the platform cert to the internal NVIDIA Minerva CA is sufficient to recover ingestion — the appended customer CA on the collector is harmless to leave in place (an extra trusted CA does nothing once the platform stops presenting it). To fully revert the trust bundle:
cd ~/minerva
./svm stack-down all
cp -a ~/cert-backup-collector-root-ca.crt secrets/ca-certs/root-ca.crt
./svm secrets
./svm stack-up all
Last updated: