DocumentationCommerceCommerce on Cloud Infrastructure Guide

Set up OpenSearch service

Last update: Thu Apr 27 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin
  • Developer

The OpenSearch service is an open-source fork of Elasticsearch 7.10.2, following the licensing changes for Elasticsearch. See the OpenSource Project in GitHub.

WARNING
Elasticsearch 7.11 and later is not supported for Adobe Commerce on cloud infrastructure. Adobe Commerce versions 2.3.7-p3, 2.4.3-p2, and 2.4.4 and later support the OpenSearch service. The on-premises installations continue to support Elasticsearch.

OpenSearch enables you to take data from any source, any format, and search and visualize it in real time.

  • Quick and advanced searches on products in the product catalog
  • OpenSearch Analyzers support multiple languages
  • Supports stop words and synonyms
  • Indexing does not impact customers until the reindex operation completes

Use the following instructions for service setup on Pro Integration environments and Starter environments, including the master branch.

NOTE
Submit an Adobe Commerce Support ticket to change the service configuration on Pro Production and Staging environments.
TIP
Adobe recommends that you always set up OpenSearch for your Adobe Commerce on cloud infrastructure project even if you plan to configure a third-party search tool for your Adobe Commerce application. Setting up OpenSearch provides a fallback option if the third-party search tool fails.

To enable OpenSearch:

  1. For Starter and Pro integration environments, add the opensearch service to the .magento/services.yaml file with the appropriate version and allocated disk space in MB. In this case, version 2 is appropriate. The minor version is not required because cloud infrastructure uses the latest version of OpenSearch.

    code language-yaml 
    opensearch:
    type: opensearch:2
    disk: 1024

    For Pro projects, you must Submit an Adobe Commerce Support ticket to change the OpenSearch version in the Staging and Production environments.

  2. Set or verify the relationships property in the .magento.app.yaml file.

    code language-yaml 
    relationships:
    opensearch: "opensearch:opensearch"

  3. Add, commit, and push code changes.

    code language-bash 
    git add .magento/services.yaml .magento.app.yaml
    code language-bash 
    git commit -m "Enable OpenSearch"
    code language-bash 
    git push origin <branch-name>

    For information on how these changes affect your environments, see Configure services.

  4. After the deployment process completes, use SSH to log in to the remote environment.

    code language-bash 
    magento-cloud ssh

  5. Reindex the Catalog Search index.

    code language-bash 
    bin/magento indexer:reindex catalogsearch_fulltext

  6. Clean the cache.

    code language-bash 
    bin/magento cache:clean
TIP
After initial service setup, you can change the software version for an installed service by updating the services.yaml and .magento.app.yaml configuration files. See Change service version for guidance on upgrading or downgrading a service.

OpenSearch software compatibility

When you install or upgrade your Adobe Commerce on cloud infrastructure project, always check for compatibility between the OpenSearch service version and the OpenSearch PHP client for Adobe Commerce.

  • First time setup–Confirm that the OpenSearch version specified in the services.yaml file is compatible with the OpenSearch PHP client configured for Adobe Commerce.

  • Project upgrade–Verify that the OpenSearch PHP client in the new application version is compatible with the OpenSearch service version installed on the cloud infrastructure.

Service version and compatibility support is determined by versions tested and deployed on the Cloud infrastructure, and sometimes differ from versions supported by Adobe Commerce on-premises deployments. See System requirements in the Installation Guide for a list of supported versions.

To verify OpenSearch software compatibility:

  1. On your local workstation, change to your project directory.

  2. Show the OpenSearch details for the active environment.

    code language-bash 
    magento-cloud relationships --property=opensearch

  3. Alternatively, you can use SSH to log in to the remote environment.

    code language-bash 
    magento-cloud ssh

  4. Retrieve the OpenSearch service connection details.

    code language-bash 
    vendor/bin/ece-tools env:config:show services

    In the response, find the IP address and port for the OpenSearch service endpoint:

    code language-terminal 
    +------------------------------------------+--------------------------------------------------------+
| opensearch:                                                                                       |
+------------------------------------------+--------------------------------------------------------+
| username                                 | null                                                   |
| scheme                                   | http                                                   |
| service                                  | opensearch                                             |
| fragment                                 | null                                                   |
| ip                                       | 169.254.220.11                                         |
| hostname                                 | hostf75wi3sd24l.opensearch.service._.magentosite.cloud |
| port                                     | 9200                                                   |
| cluster                                  | projectID-develop-4ranwui                              |
| host                                     | opensearch.internal                                    |
| rel                                      | opensearch                                             |
| path                                     | null                                                   |
| query                                    |                                                        |
| password                                 | null                                                   |
| type                                     | opensearch:2                                           |
| public                                   | false                                                  |
| host_mapped                              | false                                                  |

  5. Retrieve the installed OpenSearch service version:number from the service endpoint.

    code language-bash 
    curl -XGET <opensearch-service-endpoint-ip-address>:9200
    code language-terminal 
    {
   "name" : "opensearch.0",
   "cluster_name" : "opensearch",
   "cluster_uuid" : "_yzaae6-ywSEW1MaAF8ZPWyQ",
   "version" : {
     "distribution" : "opensearch",
     "number" : "2.5.0",
     "build_type" : "deb",
     "build_hash" : "aaaaaaa",
     "build_date" : "2023-01-23T12:07:18.760675Z",
     "build_snapshot" : false,
     "lucene_version" : "9.4.2",
     "minimum_wire_compatibility_version" : "7.10.0",
     "minimum_index_compatibility_version" : "7.0.0"
},
"tagline" : "The OpenSearch Project: https://opensearch.org/"
}
TIP
For Pro projects, you must submit an Adobe Commerce Support ticket to install or update services in Staging and Production environments only.
Indicate the service changes needed, include your updated .magento.app.yaml and services.yaml files, and state the PHP version in the ticket. For self-service changes to PHP version, extensions, or environment settings, see PHP settings in Application configuration.
For changes to a live Production environment (Pro only), you must provide a minimum of 48 hours notice to allow the Cloud infrastructure team sufficient time to marshal resources and conduct a secure upgrade.

Restart the OpenSearch service

If you need to restart the OpenSearch service, you must contact Adobe Commerce support.

Additional search configuration

  • By default, the search configuration for Cloud environments regenerates each time you deploy. You can use the SEARCH_CONFIGURATION deploy variable to retain custom search settings between deployments. See Deploy variables.

  • After you set up the OpenSearch service for your project, use the Admin UI to test the OpenSearch connection and customize OpenSearch settings for Adobe Commerce.

Add plugins for OpenSearch

Optionally, you can add plugins for OpenSearch by adding the configuration:plugins section to the OpenSearch service in the .magento/services.yaml file. For example, the following code enables the ICU analysis and Phonetic analysis plugins.

opensearch:
    type: opensearch:2
    disk: 1024
    configuration:
        plugins:
            - analysis-icu
            - analysis-phonetic

See the OpenSearch Project for more information on plugins.

Remove plugins for OpenSearch

Removing the plugin entries from the opensearch: section of the .magento/services.yaml file does not uninstall or disable the service. To fully disable the service, you must reindex your OpenSearch data after removing the plugins from your .magento/services.yaml file. This design prevents the possible loss or corruption of data that depends on these plugins.

To remove OpenSearch plugins:

  1. Remove the OpenSearch plugin entries from your .magento/services.yaml file.

  2. Add, commit, and push your code changes.

    code language-bash 
    git add .magento/services.yaml
    code language-bash 
    git commit -m "Remove OpenSearch plugin"
    code language-bash 
    git push origin <branch-name>

  3. Commit the .magento/services.yaml changes to your cloud repository.

  4. Reindex the Catalog Search index.

    code language-bash 
    bin/magento indexer:reindex catalogsearch_fulltext

  5. Clean the cache.

    code language-bash 
    bin/magento cache:clean
05f2f56e-ac5d-4931-8cdb-764e60e16f26