Documentation

Upgrading to Elasticsearch 7

Elasticsearch 7 is supported for the latest Liferay 7.2, 7.3, and 7.4 version out of the box. For specific version compatibility details, refer to the Search Engine Compatibility Matrix.

For Liferay 7.2, Elasticsearch 7 is supported via the Liferay Connector to Elasticsearch 7 (version 3.x). If you’re upgrading to Liferay 7.3+ or bringing your existing 7.2 search engine to Elasticsearch 7, you must upgrade your Elasticsearch servers. To set up a new Liferay 7.2 system, install Elasticsearch 7 and follow the installation guide.

Important

Before upgrading Elasticsearch, back up your existing data. If something goes wrong during or after the upgrade, roll back to the previous version using the uncorrupted index snapshots. Follow the steps in Backing up Elasticsearch.

To upgrade an existing Elasticsearch server (or cluster) to Elasticsearch 7,

  1. Back up the Liferay Company and System Indexes.

  2. Back up the application specific indexes for Search Tuning (Synonym Sets and Result Rankings).

  3. Install and configure Elasticsearch.

  4. Upgrade Elasticsearch

  5. If you’re using X-Pack security, make sure it’s enabled:

    xpack.security.enabled: true
    

    See Securing Elasticsearch for detailed coverage of the security configuration.

  6. [7.2 only] Blacklist the bundled Liferay Connector to Elasticsearch 6 and install the Connector to Elasticsearch 7.

  7. Configure the Connector to Elasticsearch 7 to connect to Elasticsearch.

  8. Restart Liferay, then re-index all search and spell check indexes.

  9. Restore Search Tuning indexes from the snapshot. If you were previously using these features, you may have data stored in these indexes.

  10. Verify that Search Tuning entries have been carried over.

Upgrading Elasticsearch

If you are using a rolling-restart eligible version (6.8.x), doing a rolling upgrade is the recommended way to upgrade your Elasticsearch cluster. Otherwise, follow the full cluster restart upgrade guide.

If you’ve installed a new Elasticsearch server and want to index your pre-upgrade data, most Liferay indexes can be restored by triggering a re-index from the UI, once the Liferay database is upgraded. However, the Search Tuning (Result Rankings and Synonyms) indexes and any custom indexes not backed by database storage must be restored from a snapshot of the pre-upgrade indexes.

Blacklisting Elasticsearch 6

This is only necessary if running Liferay 7.2.

  1. Create a configuration file named

    com.liferay.portal.bundle.blacklist.internal.BundleBlacklistConfiguration.config
    
  2. Give it these contents:

    blacklistBundleSymbolicNames=[ \
        "com.liferay.portal.search.elasticsearch6.api", \
        "com.liferay.portal.search.elasticsearch6.impl", \
        "com.liferay.portal.search.elasticsearch6.spi", \
        "com.liferay.portal.search.elasticsearch6.xpack.security.impl", \
        "Liferay Connector to X-Pack Security [Elastic Stack 6.x] - Impl", \ 
        "Liferay Enterprise Search Security  - Impl" \
    ]
    
  3. Deploy the file by copying it to your server’s deploy folder.

Restart Liferay and Re-Index

Once Liferay is connected with the Elasticsearch cluster, restart Liferay and re-index the applicable indexes into the new Elasticsearch installation:

  1. Restart Liferay.

  2. Re-index the company, system, and spell check indexes. From the Global Menu (Global Menu), navigate to Control PanelConfigurationSearch. Click Execute for the Reindex all search indexes entry.

  3. Re-index the Workflow Metrics indexes: from the Global Menu (Global Menu), navigate to ApplicationsWorkflow—Metrics. Open the Settings menu (Options and Click Reindex All. Repeat the process for each Virtual Instance.

This restores the indexes built from data stored in the Liferay database. To restore indexes used as primary storage, see Backing Up Elasticsearch.

Liferay 7.2: Reverting to Elasticsearch 6

Stuff happens. If you’re on Liferay 7.2 and that stuff involves an unrecoverable failure during the upgrade to Elasticsearch 7, you can roll back to Elasticsearch 6 and regroup.

Since your Elasticsearch 6 and 7 are currently two separate installations, this procedure takes only a few steps:

  1. Stop the Liferay Connector to Elasticsearch 7.

  2. Stop Elasticsearch 7 and make sure that the Elasticsearch 6 elasticsearch.yml and the connector app are configured to use the same port (9200 by default).

  3. Remove the blacklist configuration file for Elasticsearch 6 from your installation’s osgi folder.

  4. Start the Elasticsearch server and then restart the Liferay Connector to Elasticsearch 6.

Once your upgrade is completed, see the new search features available in your Liferay version..