Migrate Solr Collections

Last updated
Save as PDF

For supported software information, click here.

When you perform an Analytics upgrade that upgrades the Solr version on existing nodes, collections (search indexes) created on the older Solr version can become incompatible with the newer Solr version. To address this issue, you can migrate the existing Solr collections to the new release after upgrading Analytics. You do this by running the van_cluster_installer.py script from an upgraded Director node. While you typically run the script immediately after upgrading Analytics and Director, you can run the script at any time after upgrading to Release 22.1.4 (Service Release dated 2025-06-27) or later.

The van_cluster_installer.py script performs the following operations to migrate the Solr collections:

Creates new collections with version-specific naming.
Uses intelligent aliasing to read from both old and new collections while writing to new ones.
Automatically migrates data over time.
Removes old collections only when they're completely empty.

This article describes how to migrate Solr collections using the van_cluster_installer.py script.

Script Requirements

To migrate Solr collections using the van_cluster_installer.py script, your system must meet the following requirements:

Versa Analytics Release 22.1.4 (Service Release dated 2025-06-27) or later.
Versa Director Release 22.1.4 (Service Release dated 2025-06-27) or later.
Administrative access to the Director node.
Network connectivity between Director and Analytics nodes.

Frequently Asked Questions

Will the migration process affect my current Analytics or Search data?

No, all existing data remains accessible. The migration only adds new collections and aliases.

How long does the migration take?

The upgrade typically takes 5-10 minutes to complete, depending on cluster size. The process runs in the background.

Can I continue using Analytics during the migration?

Yes, Analytics remains functional during the migration process. There may be a very brief interruption when the collection aliases are being switched, during which new data ingestion may be temporarily affected. This typically takes only a few seconds.

What if the migration fails?

You can safely retry the migration. Failed migrations do not affect existing data or functionality.

Can I perform the migration from the Analytics UI?

The script must be run from the Director command line.

Migrating Solr Collections

You typically migrate Solr collections after an upgrade of Analytics, although you can run the van_cluster_installer.py script at any time after upgrading Analytics and Director to Release 22.1.4 (Service Release dated 2025-06-27) and later. For the full upgrade procedure, which includes running the script, see Upgrade Software on Headend and Branch.

You can also perform a standalone migration of Solr collections using the van_cluster_installer.py script. The following table describes the script options for upgrade and standalone scenarios.

Scenario	Recommended Option	Description
Migrate collections after upgrading both Analytics and Director nodes to Release 22.1.4 (Service Release dated 2025-06-27) or later.	--post-upgrade	Post-upgrade procedures. This option performs the following tasks: Package version verification Migration Other post-upgrade configurations
Standalone Migration	--search-collection-upgrade	Migration only.
Retry Failed Migration	--search-collection-upgrade	Retry only the migration step.

Scenario

Recommended Option

Description

Migrate collections after upgrading both Analytics and Director nodes to Release 22.1.4 (Service Release dated 2025-06-27) or later.

--post-upgrade

Post-upgrade procedures. This option performs the following tasks:

Package version verification
Migration
Other post-upgrade configurations

Standalone Migration

--search-collection-upgrade

Migration only.

Retry Failed Migration

--search-collection-upgrade

Retry only the migration step.

Troubleshoot Script Errors

The following table describes possible errors you may encounter when running the updated van_cluster_installer.py script, and possible solutions.

Error Message	Problem Description	Solution
"Unable to reach Analytics app"	Cannot connect to Analytics nodes	On each node in the Analytics cluster, verify that Analytics services are running: admin@Analytics$ vsh status If required, restart Analytics services: admin@Analytics$ vsh restart On the Director node, verify network connectivity to each node in the Analytics cluster: admin@Director$ nc -zw3 <analytics-IP-address> 443 admin@Director$ nc -zw3 <analytics-IP-address> 8443
"Package version mismatch detected"	Not all nodes are on the same Analytics package version	On each node in the Analytics cluster, verify the package version. admin@Analytics$ cli admin@Analytics> show system package-info Rerun the package upgrade to ensure all nodes are on the same version. admin@Director$ sudo ./van_cluster_installer.py --pkg-upgrade analytics-package.bin
"Authentication failed"	Incorrect Analytics UI password	Note that the van_cluster_installer.py script accesses the Analytics application using the Analytics UI admin account. The script uses one of the following passwords when logging into the admin account: If configured, the script uses the password listed in the ui_password entry in the /opt/versa/vnms/scripts/van-cluster-config/van_cluster_install/clustersetup.conf file. If needed, the script prompts you for the Analytics UI admin password. If authentication fails, ensure you have the correct password for the admin account. You can reset the Analytics UI admin password by issuing the following command on any node in the cluster: admin@Analytics$ sudo /opt/versa/scripts/van-scripts/AdminManager.sh
"Collection upgrade did not complete"	Migration timeout or failure	Check logs for detailed error messages. To do this, run the following command on the Analytics Search node with the smallest IP address. admin@Search$ tail -f /var/log/versa/versa-solr-reindexing.log Retry the migration. admin@Director$ sudo ./van_cluster_installer.py --search-collection-upgrade Check the current collection status. To do this, run the following command on the Analytics Search node with the smallest IP address. admin@Search$ sudo /opt/versa/scripts/van-install/cluster_install.sh solr cluster_status

Supported Software Information

Releases 22.1.4 (Service Release dated 2025-06-27) and later support all content described in this article.