Upgrade Minerva on Docker Swarm | NVIDIA Minerva User Guide

This procedure upgrades an existing NVIDIA Minerva Docker Swarm deployment in place. It covers unified, platform, and collector deployment types on either a single-node or multi-node Swarm. An upgrade cannot change the deployment type, and requires a planned outage — keep each Swarm stopped until every node in that Swarm has been upgraded.

Before You Begin

Confirm all of the following:

NVIDIA has approved the upgrade path from the installed version to the target version.
The installer matches the deployment and delivery method:
- Standard installer for a registry-based installation
- All-image installer for a bundled unified or platform installation
- Collector installer for a bundled collector installation
The installer is available on every node.
The same installation user will run the upgrade on every node.
The installer is in that user's home directory. The following commands assume the installation is at ~/minerva.
Every standard-installer node can reach and authenticate to its configured container registry.
A maintenance window covers the platform and every associated collector.

On each node, set the exact target installer filename. Replace the example value before running any later command:

cd ~
INSTALLER="installer.minerva.REPLACE_WITH_TARGET_BUILD"
chmod +x "$INSTALLER"

For a bundled deployment, use the applicable installer.minerva.all.REPLACE_WITH_TARGET_BUILD or installer.minerva.collector.REPLACE_WITH_TARGET_BUILD filename instead.

If the registry requires authentication, run docker login on every standard-installer node before the maintenance window.

Record the Current Deployment

On each Swarm manager, record the installed version and service state:

cd ~/minerva
cat VERSION
./svm stack-status
docker node ls

Keep the output with the maintenance record. Also preserve the current deploy-cfg.yml, parameters, registry/image-source configuration, and any local compose or stack override files in secure storage outside the host.

Back up the Deployment

Run backups while the services are still running.

Platform or Unified Deployment

Run the configured application backup from the platform or unified manager:

minerva-cli backup --yes --all save
minerva-cli backup list

Verify that the new backup appears at the expected destination.

--all means all services listed in the deployment's backup configuration. It is not a complete host or storage snapshot. If the recovery plan requires additional databases, local time-series data, object storage, or host state, complete the Support-approved backup or snapshot procedure before continuing.

Create a separate backup of local and runtime secrets on every Swarm manager:

cd ~/minerva
./svm secrets-backup
ls -lt ~/minerva_secret_backups

Do not continue if secrets-backup reports an incomplete backup. Copy the new archive from ~/minerva_secret_backups to secure storage outside the host.

Collector Deployment

Do not run minerva-cli backup on a collector; the application-backup command is not supported in collector mode.

On every collector manager, run and verify the secrets backup:

cd ~/minerva
./svm secrets-backup
ls -lt ~/minerva_secret_backups

Preserve the collector's deploy-cfg.yml, platform CA certificate, collector RSA private key, and mTLS client certificate and key in secure storage outside the host. These materials maintain the collector's trust relationship with its platform.

Optional: Preload Images

On a host that already uses the ~/minerva path, the target installer can download or load images before the outage:

cd ~
./"$INSTALLER" -d

Run this on every node that will be upgraded.

Upgrade a Single-node Deployment

This procedure applies to a single-node unified, platform, or collector Swarm.

Stop all stacks:
```
cd ~/minerva
./svm stack-down all
```
Run the target installer from the home directory:
```
cd ~
./"$INSTALLER"
```
Do not provide a Swarm join token during an in-place upgrade. The installer preserves the existing deployment type and configuration.

Start and verify the deployment:

cd ~/minerva
cat VERSION
./svm stack-up all
./svm stack-status

Upgrade a Multi-node Deployment

Upgrade every node in the Swarm with the same target build and installer family. Existing nodes remain members of the Swarm; do not use -s and do not provide new join tokens.

From the primary manager, stop the complete Swarm deployment:
```
cd ~/minerva
./svm stack-down all
```
Upgrade the primary manager:
```
cd ~
./"$INSTALLER"
```
Run the same target installer on every additional manager and worker:
```
cd ~
./"$INSTALLER"
```
Keep the stacks stopped until all nodes report the target version:
```
cat ~/minerva/VERSION
```

From the primary manager, start and verify the deployment:

cd ~/minerva
./svm stack-up all
./svm stack-status
docker node ls

Do not start a Swarm that contains a mixture of old and target installation files unless the release-specific upgrade plan explicitly permits it.

Upgrade a Hybrid Platform and its Collectors

The platform and each collector are independent Swarms. Running a command on the platform manager does not stop, upgrade, or start any collector Swarm.

Use this order for a coordinated outage:

Complete the platform application backup.
Back up secrets on the platform manager and every collector manager.
Stop every collector Swarm.
Stop the platform Swarm.
Upgrade every platform node.
Upgrade every node in each collector Swarm.
Start and validate the platform.
Start and validate each collector.

On every collector manager, stop its stacks:

cd ~/minerva
./svm stack-down all

On the platform manager, stop the platform stacks:

cd ~/minerva
./svm stack-down all

Upgrade every node in the platform Swarm using the standard installer or the all-image installer, as appropriate. Then upgrade every node in each collector Swarm using the standard installer or collector installer, as appropriate.

An existing collector normally preserves its bootstrap material and does not need a new bootstrap bundle for an ordinary upgrade. If the installer reports that the platform CA, collector RSA key, mTLS client pair, or platform address is missing, stop. Restore the existing material or provide a bootstrap bundle generated by the associated platform. Do not create an unrelated trust chain.

Start and validate the platform first:

cd ~/minerva
./svm stack-up all
./svm stack-status

After the platform UI and API are available, start and validate each collector from that collector's manager:

cd ~/minerva
./svm stack-up all
./svm stack-status

Validate the Upgrade

Confirm all of the following:

cat ~/minerva/VERSION shows the target version on every node.
docker node ls shows every expected node as ready from each Swarm manager.
./svm stack-status shows the expected services running on every manager.
The platform UI and API are reachable.
Authentication succeeds for an administrative user.
Telemetry arrives from every collector and representative data sources.
Alerts, scheduled backups, and any configured support upload operate as expected.
The configured node placement matches the intended topology.

On a platform or unified manager, the following commands can help capture the installed distribution:

minerva-cli support show-hosts
minerva-cli support show-distribution

If the Upgrade Fails

Do not start a partially upgraded Swarm. Preserve the installer log written beside the installer and the svm logs under the configured runtime log directory.

The installer creates a versioned copy of the previous installation tree, normally ~/minerva_<previous-version>. This is not a complete rollback: service data can be upgraded in place, and old container images can be removed. Do not rerun an older installer as a generic downgrade procedure.

If NVIDIA Support directs a secret restoration, stop all stacks before using the verified archive:

cd ~/minerva
./svm stack-down all
SECRET_ARCHIVE="$HOME/minerva_secret_backups/REPLACE_WITH_VERIFIED_ARCHIVE.tar.gz"
./svm secrets-restore --force "$SECRET_ARCHIVE"

A failed database upgrade, secret import, or multi-node upgrade requires a Support-approved recovery plan. The current source does not define a generally supported downgrade procedure.

Last updated: October 13, 2026