Set up Elasticsearch service

Elasticsearch is an open source product that enables you to take data from any source, any format, and search and visualize it in real time.

  • Elasticsearch performs quick and advanced searches on products in the product catalog
  • Elasticsearch 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 Adobe Commerce on cloud infrastructure Pro Integration environments and Starter environments, including the master branch.

You must submit a support ticket to change the service configuration on Pro Production and Staging environments. See Services.

Adobe recommends that you always set up Elasticsearch 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 Elasticsearch provides a fallback option in the event that the third-party search tool fails.

To enable Elasticsearch:

  1. For Starter projects, add the elasticsearch service to the .magento/services.yaml file with the Elasticsearch version and allocated disk space in MB.

    1
    2
    3
    
    elasticsearch:
        type: elasticsearch:<version>
        disk: 1024
    

    For Pro projects, you must submit a Adobe Commerce Support ticket to change the Elasticsearch version.

    For details on determining the correct version to install, see Elasticsearch software compatibility.

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

    1
    2
    
    relationships:
        elasticsearch: "elasticsearch:elasticsearch"
    
  3. Add, commit, and push code changes.

    1
    
    git add -A && git commit -m "Enable Elasticsearch" && git push origin <branch-name>
    

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

  4. Verify the service relationships and configure Elasticsearch in the Admin UI.

  5. Reindex the Catalog Search index.

    1
    
    bin/magento indexer:reindex catalogsearch_fulltext
    
  6. Clean the cache.

    1
    
    bin/magento cache:clean
    

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.

Elasticsearch software compatibility

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

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

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

The following table lists compatible versions of the Elasticsearch software supported by Adobe Commerce.

Elasticsearch service Elasticsearch composer package Status
5.2.x 5.x.x default versions for Adobe Commerce versions 2.2.x to 2.2.7 and 2.3.0
6.8 6.7.x recommended, default versions for Adobe Commerce versions 2.2.8 and 2.3.4
7.7 7.x recommended, default versions for Adobe Commerce versions 2.3.5 and 2.4.x

Version support and compatibility for Adobe Commerce on cloud infrastructure is determined by service versions deployed on the Cloud infrastructure. In some cases, the supported or recommended versions differ from the versions supported by Adobe Commerce on-premises deployments.

To check Elasticsearch software compatibility:

  1. Use SSH to log in to the remote environment.

  2. Check the Composer package version for elasticsearch/elasticsearch.

    1
    
    composer show elasticsearch/elasticsearch
    

    In the response, check the installed version in the versions property.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    
    name     : elasticsearch/elasticsearch
    descrip. : PHP Client for Elasticsearch
    keywords : client, elasticsearch, search
    versions : * v6.7.1
    type     : library
    license  : Apache License 2.0 (Apache-2.0) (OSI approved) https://spdx.org    licensesApache-2.0.html#licenseText
    source   : [git] https://github.com/elastic    elasticsearch-php.git7be453dd36d1b141b779f2cb956715f8e04ac2f4
    dist     : [zip] https://api.github.com/repos/elastic/elasticsearch-php/zipball/     7be453dd36d1b141b779f2cb956715f8e04ac2f4 7be453dd36d1b141b779f2cb956715f8e04ac2f4
    path     : /app/vendor/elasticsearch/elasticsearch
    names    : elasticsearch/elasticsearch
    

    Also, you can find the Elasticsearch PHP client version in the composer.lock file in the environment root directory.

  3. From the command line, retrieve the Elasticsearch service connection details.

    1
    
    vendor/bin/ece-tools env:config:show services
    

    In the response, find the IP address for the Elasticsearch service endpoint:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    
    | elasticsearch:                                                                                                  |
    +------------------------------------------+----------------------------------------------------------------------+
    | username                                 | null                                                                 |
    | scheme                                   | http                                                                 |
    | service                                  | elasticsearch                                                        |
    | fragment                                 | null                                                                 |
    | ip                                       | 169.254.220.11                                                       |
    | hostname                                 | dzggu33f75wi3sd24lgwtoupxm.elasticsearch.service._.magentosite.cloud |
    | public                                   | false                                                                |
    | cluster                                  | fo3qdoxtla4j4-master-7rqtwti                                         |
    | host                                     | elasticsearch.internal                                               |
    | rel                                      | elasticsearch                                                        |
    | query                                    |                                                                      |
    | path                                     | null                                                                 |
    | password                                 | null                                                                 |
    | type                                     | elasticsearch:6.5                                                    |
    | port                                     | 9200                                                                 |
    +------------------------------------------+----------------------------------------------------------------------+
    
  4. Retrieve the installed Elasticsearch service version:number from the service endpoint.

    1
    
    curl -XGET <elasticsearch-service-endpoint-ip-address>:9200/
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    
    {
       "name" : "-AqGi9D",
       "cluster_name" : "elasticsearch",
       "cluster_uuid" : "_yze6-ywSEW1MaAF8ZPWyQ",
       "version" : {
         "number" : "6.5.4",
         "build_flavor" : "default",
         "build_type" : "deb",
         "build_hash" : "82a8aa7",
         "build_date" : "2019-01-23T12:07:18.760675Z",
         "build_snapshot" : false,
         "lucene_version" : "7.5.0",
         "minimum_wire_compatibility_version" : "5.6.0",
         "minimum_index_compatibility_version" : "5.0.0"
    },
    "  tagline" : "You Know, for Search"
    }
    
  5. Check version compatibility between the Elasticsearch service and the PHP client.

    If the versions are incompatible, make one of the following updates to your environment configuration:

    • Change the Elasticsearch PHP client to a version that is compatible with the Elasticsearch service version.

    • Change the Elasticsearch service version in the services.yaml file to a version that is compatible with the Elasticsearch PHP client.

      For Pro projects, you must create a Support ticket to install or update services in Staging and Production environments. Indicate the service changes needed and include your updated .magento.app.yaml and services.yaml files in the ticket. It can take up to 48 hours for the Cloud infrastructure team to update your project.

Restart the Elasticsearch service

If you need to restart the Elasticsearch 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 Elasticsearch service for your project, use the Admin UI to test the Elasticsearch connection and customize Elasticsearch settings for Adobe Commerce.

Add plugins for Elasticsearch

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

1
2
3
4
5
6
7
elasticsearch:
    type: elasticsearch:<service-version>
    disk: 1024
    configuration:
        plugins:
            - analysis-icu
            - analysis-phonetic

If you use the ElasticSuite third-party plugin, you must update the ece-tools package to version 2002.0.19 or later. When setting up ElasticSuite, add the configuration settings to the ELASTICSUITE_CONFIGURATION deploy variable. This configuration saves the settings across deployments.

Remove plugins for Elasticsearch

Removing the plugin entries from elasticsearch: in .magento/services.yaml does not uninstall or disable them as you might expect. You must take the additional step of reindexing your Elasticsearch data. This behavior is intentional to prevent possible loss or corruption of data that depends on these plugins.

To remove Elasticsearch plugins:

  1. Remove the Elasticsearch plugin entries from your .magento/services.yaml file.
  2. Add, commit, and push your code changes.

    1
    
    git add -A
    
    1
    
    git commit -m "Remove Elasticsearch plugin"
    
    1
    
    git push origin <branch-name>
    
  3. Commit the .magento/services.yaml changes to your Cloud repo.
  4. Reindex the Catalog Search index:

    1
    
     bin/magento indexer:reindex catalogsearch_fulltext
    
  5. Clean the cache:

    1
    
     bin/magento cache:clean
    

For details on using or troubleshooting the Elasticsuite plugin with Adobe Commerce, see the Elasticsuite documentation.

Troubleshooting

See the following Adobe Commerce Support articles for help troubleshooting Elasticsearch problems: