Introduction

Starting with SolrCloud Search Service Adapter 7.3.0, Intershop Commerce Management (ICM) supports Solr 9.10 as the search backend. This document explains how to migrate the Solr adapter and server from Apache Solr 8 to Solr 9.

This document is intended for developers and administrators.

References

• Reference - ICM 14 Release Versions

• Public Release Note - SolrCloud Search Service Adapter 7

• Apache Solr Reference Guide

Upgrade the SolrCloud Search Service Adapter

The SolrCloud Search Service Adapter 7.3.0 supports Solr 9. Upgrade the adapter in the ICM deployment. Reference version 7.3.0 in the customizations.solr section of version.yaml.

  customizations:
    solr:
      repository: ${icm_container_registry}/icm-as-customization-f_solrcloud:7.3.0

Update project customizations that extend the SolrCloud adapter to reference version 7.3.0. Update project cartridges that depend on the com.intershop.solrcloud group.

    cartridge("com.intershop.solrcloud:ac_solr_cloud")

Default Solr Configuration Changes

The adapter removes the numVersionBuckets line from the update log configuration of the solrconfig.xml. This setting is obsolete in Solr 9 and causes frequent warning messages (#119384).

    <updateLog>
      <str name="dir">${solr.ulog.dir:}</str>
      <int name="numVersionBuckets">${solr.ulog.numVersionBuckets:65536}</int>
    </updateLog>

The adapter leaves the other configuration files unchanged. The managed-schema file is compatible with Solr 9.

Adapt project-specific Solr configurations that override or extend solrconfig.xml. Remove the numVersionBuckets setting from these configurations. Refer to the Apache Solr Reference Guide - Upgrade Guide for other required changes. Test each customization on the INT and UAT systems before upgrading the production servers.

Upgrade the Solr Configuration on the Solr Server

Upgrade the default Solr configuration in all configuration sets:

1. Run the Job - Cleanup Search Indexes job. The job cleans all aliases, collections, and configuration sets, including the default configuration set.

2. Rebuild all search indexes with the Job - Rebuild Search Indexes job.

3. Run data replication for the Search Indexes replication group. The Replication transfers the new configuration to the live environment.

As an alternative, use a migration step with the updated solrconfig.xml:

1. Create migration-to-1.2.3.properties.

2. Add the edited solrconfig.xml as a resource in the migration cartridge.

Class1 = com.intershop.adapter.search_solr.dbmigrate.preparer.SolrConfigSetUploadPreparer \
          /com/project/dbmigrate/data/search/solrconfig.xml solrconfig.xml \
          text/xml stagingSystemType=EDITING,NONE 

Upgrade the Solr Server

For cloud customer deployments, the Operations team performs the following steps.

Migrate Permissions

Solr 9 removes permissions that Solr 8 deployments use in the default security configuration. These obsolete permissions cause error messages in Solr 9. Remove the following permissions before upgrading the Solr server:

• metrics-history-read

• autoscaling-read

• autoscaling-write

Use the migrate-solr-security-pe… to remove obsolete permissions. The script backs up the authorization policy before and after each run.

Remove the obsolete permissions:

1. Run the script with a user that has the admin role. Use dry-run mode to review the planned changes:

./migrate-solr-security-permissions.sh \
  'admin:SolrRocks' \
  'https://<solr-host>/solr' \
  'metrics-history-read,autoscaling-read,autoscaling-write'

2. Review the planned removals in the script output.

3. Apply the changes:

./migrate-solr-security-permissions.sh \
  'admin:SolrRocks' \
  'https://<solr-host>/solr' \
  'metrics-history-read,autoscaling-read,autoscaling-write' \
  apply

4. Confirm that the script reports Migration successful. Check the security-migration-backups directory for the authorization policies before and after the change.

Requirements: curl and jq.

Perform a Rolling Upgrade of the Solr Server

Use the following restart sequence to upgrade the server with minimal downtime. During the sequence, Solr 8 and Solr 9 nodes continue to forward and answer user requests. For background information, see Solr Reference Guide - Rolling Upgrades.

1. Upgrade the Solr image and version. Add system properties for PKI security during internal request forwarding:

      solr_image:  "ishcp.azurecr.io/cache/dockerhub/library/solr"
      solr_version: "9.10.1"
      solr_java_opts: "-Dsolr.pki.sendVersion=v1 -Dsolr.pki.acceptVersions=v1,v2"

2. Restart all Solr nodes. Set the PKI send version to v2:

      solr_java_opts: "-Dsolr.pki.acceptVersions=v1,v2"

3. Restart all Solr nodes. Configure the server to accept only v2, and remove the additional options.

During off-duty hours, when no user requests are expected, update the image and version directly. Restart the Solr nodes once instead of following the three-step sequence.

  solr_image:  "ishcp.azurecr.io/cache/dockerhub/library/solr"
  solr_version: "9.10.1"

Local Project Development with Solr 9

Update the icm-docker-plugin to version 7.4.0 in settings.gradle.kts for local development environments that use Solr in Docker with gradlew startSolrCloud.

pluginManagement {
    val dockerPluginVersion = "7.4.0"
...

Update the Solr image version in the project's build.gradle.kts file to use the latest Solr 9 version, or pin it to a specific version, such as 9.10.1.

intershop_docker {
    images {
...
        solr.set("solr:9")
...

The new icm-docker-plugin deprecates solr.zooKeeperHostList. Replace it with solr.cloudSolrServerURLs in icm.properties.

solr.cloudSolrServerURLs = http://localhost:8983/solr

The plugin also provides options for local development with a multi-node Solr cluster. See the task configuration properties in GitHub: icm-docker-plugin | Intershop Commerce Management - Docker Plugins.