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.

Service version and compatibility support for Adobe Commerce on cloud infrastructure is determined by versions deployed on the cloud infrastructure, and sometimes differ from versions supported by Adobe Commerce on-premises deployments. See Service versions.

To check Elasticsearch software compatibility:

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

  2. Show the Elasticsearch details for the active environment.

    magento-cloud relationships --property=elasticsearch
    
  3. Alternatively, you can use SSH to log in to the remote environment.

    magento-cloud ssh
    
  4. Check the Composer package version for elasticsearch/elasticsearch.

    composer show elasticsearch/elasticsearch
    

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

    name     : elasticsearch/elasticsearch
    descrip. : PHP Client for Elasticsearch
    keywords : client, elasticsearch, search
    versions : * v7.17.1
    type     : library
    license  : Apache License 2.0 (Apache-2.0) (OSI approved) https://spdx.org/licenses/Apache-2.0.html#licenseText
    license  : GNU Lesser General Public License v2.1 only (LGPL-2.1-only) (OSI approved) https://spdx.org/licenses/LGPL-2.1-only.html#licenseText
    homepage :
    source   : [git] git@github.com:elastic/elasticsearch-php.git f1b8918f411b837ce5f6325e829a73518fd50367
    dist     : [zip] https://api.github.com/repos/elastic/elasticsearch-php/zipball/f1b8918f411b837ce5f6325e829a73518fd50367 f1b8918f411b837ce5f6325e829a73518fd50367
    path     : ~/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.

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

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

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

    | 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                                                                 |
    +------------------------------------------+----------------------------------------------------------------------+
    
  6. Retrieve the installed Elasticsearch service version:number from the service endpoint.

    curl -XGET <elasticsearch-service-endpoint-ip-address>:9200/
    
    {
       "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"
    }
    
  7. 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.

      composer require "elasticsearch/elasticsearch:~<version>"
      
    • Change the Elasticsearch service version in the services.yaml file to a version that is compatible with the Elasticsearch PHP client.

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), a minimum of 48 hours notice is required. This allows the Cloud infrastructure team sufficient time to marshal resources and conduct a secure upgrade. The notice period begins when the Infrastructure team acknowledges the request and schedules the upgrade, excluding weekends. For example, to have service upgrades completed on a Monday, an acknowledgement of the scheduled upgrade must be received by Wednesday. During peak demand periods, it might take more time to process your request.

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.

elasticsearch:
    type: elasticsearch:<service-version>
    disk: 1024
    configuration:
        plugins:
            - analysis-icu
            - analysis-phonetic

If you use the Elastic Suite third-party plugin, you must update the ece-tools package to version 2002.0.19 or later.
When setting up Elastic Suite, 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 reindex 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.

    git add .magento/services.yaml
    
    git commit -m "Remove Elasticsearch plugin"
    
    git push origin <branch-name>
    
  3. Commit the .magento/services.yaml changes to your Cloud repo.

  4. Reindex the Catalog Search index.

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

    bin/magento cache:clean
    
TIP
For details on using or troubleshooting the Elastic Suite plugin with Adobe Commerce, see the Elastic Suite documentation.
Previous pageConfigure services

Commerce