Install Collectors for a Hybrid Deployment

Install each collector after the Platform Stack is running, in this order:

1. Create a collector bootstrap bundle on the platform.

2. Run the collector installer.

3. Configure deploy-cfg.yml.

4. Add worker nodes (multi-node collectors only).

5. Bring up the stacks.

Create a Collector Bootstrap Bundle

The bundle tells the collector how to reach the Platform Stack and gives it its identity. It contains the platform and Kafka addresses, the platform root CA, the collector's client certificate and key, and its collector ID. Create one bundle for each collector.

1. Choose a collector ID: exactly 8 hexadecimal digits, unique for each collector. To generate one:

   python3 -c "import secrets; print(secrets.token_hex(4))"
   

2. On the platform manager node, create the bundle:

   cd ~/minerva
   ./svm collector-bundle <collector-id>
   

   This writes ~/minerva/collector-bootstrap-<collector-id>.tar.gz.

   • All nodes of one collector install the same bundle and share its ID. A collector that needs its own identity needs its own bundle.

   • To reissue an existing bundle, add --force. Collectors already installed from the old bundle keep working. The reissued bundle has a new key pair, the same name, and the same CA; nothing is revoked.

3. Copy the bundle and the collector installer to the collector's manager node:

   scp ~/minerva/collector-bootstrap-<collector-id>.tar.gz <user>@<collector-host>:~/
   scp installer.minerva.collector.<BUILD> <user>@<collector-host>:~/
   

   The bundle contains the collector's private key. On the collector's manager node, restrict it to the install user:

   chmod 600 ~/collector-bootstrap-<collector-id>.tar.gz
   

Run the Collector Installer

1. On the collector's manager node, run the installer with your bundle:

   chmod +x installer.minerva.collector.<BUILD>
   COLLECTOR_BOOTSTRAP_BUNDLE=~/collector-bootstrap-<collector-id>.tar.gz ./installer.minerva.collector.<BUILD>
   

   The collector installer includes all collector images and doesn't ask for a deployment type. You can also use the standard installer (installer.minerva.<BUILD>): select collector when prompted, and make sure the node can reach the container registry.

   On ARM64 hosts, use installer.minerva.collector.arm64.<BUILD>.

2. Answer the installer prompts (see Installer prompts). Enter ? at any prompt for help. The installer skips prompts that the bundle or a previous run already answered. With COLLECTOR_BOOTSTRAP_BUNDLE set, it prints Collector identity: <collector-id> and doesn't ask for the bundle path or the Kafka address.

If the installer prints error: crontab failed at the end, see User Setup in Prepare Hosts for Docker Swarm.

Configure deploy-cfg.yml

The installer creates and configures deploy-cfg.yml. Merge only approved local overrides into it, for example the proxy.

• Don't change conf.ingestion.class or conf.collector.id. They hold the collector ID from the bundle. To change the ID, reinstall with a different bundle.

Add Worker Nodes (Multi-Node Collectors Only)

1. On the collector's manager node, get the join token:

   docker swarm join-token worker
   

2. On each worker node, run the installer with the token:

   chmod +x installer.minerva.collector.<BUILD>
   ./installer.minerva.collector.<BUILD> -s "worker <token> <addr:port>"
   

   Workers don't need the bundle and show no prompts. They get their secrets from the collector's manager node.

Bring Up the Stacks

1. From ~/minerva/ on the collector's manager node, start the stacks and check their status:

   ./svm stack-up all
   ./svm stack-status
   

2. Confirm that switch-connector is registered and ready. docker service ls showing 1/1 isn't enough: a collector with the wrong identity, or without Kafka access, stays Running but isn't ready.

   docker service ls | grep switch-connector
   docker service logs --since 2m backend_switch-connector 2>&1 | grep -E "registered with mgmt|started|assigned partitions|ERROR"
   

   A healthy collector logs switch-connector registered with mgmt, switch-connector started with "collectorId": "<collector-id>", and connector was assigned partitions, with no ERROR lines.

If the platform isn't reachable on port 9093, or the collector's identity isn't valid, switch-connector doesn't restart. It stays up and logs errors:

• Port 9093 blocked: Message timed out, 1/1 brokers are down, the ownership topic cannot be read ... NOT ready, and could not publish its heartbeat. It recovers on its own once the port is open.

• Wrong identity (common bundle): Topic authorization failed.

Reinstall or Move a Collector

1. On the collector's manager node, stop the stacks: ./svm stack-down all. If the stacks are running, the installer refuses to continue (backend stack is running. Stop it by executing ./svm stack-down backend), but only after it has already imported the new certificate files.

2. Run the installer with the new bundle, and then run ./svm stack-up all.

Installing with a bundle replaces the node's identity: root CA, client certificate, key, and collector ID. An upgrade without a bundle keeps the existing identity. When a collector moves to a new ID, the old ID's topics and registration stay on the platform.

For upgrades, see Upgrade NVIDIA Minerva on Docker Swarm.

Last updated: October 30, 2026