1. Liferay Help Center
  2. Knowledge Base
  3. How-to

How to configure Liferay DXP to connect to Elasticsearch on Elastic Cloud

Avatar

Tibor Lipusz

  • Updated

This article shows an example configuration only and assumes a familiarity with configuring Liferay DXP with Elasticsearch in a local/on-premise deployment.

Table of Contents

Environment - Elastic Stack

  • Liferay DXP 7.4 Update 96* + Elasticsearch 8.10.2**
  • Liferay DXP 7.4 Update 96* + Elasticsearch 7.17.13**
  • Liferay DXP 7.3 Update 33* + Elasticsearch 8.10.2**
  • Liferay DXP 7.3 Update 33* + Elasticsearch 7.17.13**
  • Liferay DXP 7.2 (FP8)* + Liferay Connector to Elasticsearch 7 (v3.1.0)* + Elasticsearch 7.11.0**

Versions last updated: October 2, 2023

Resolution - Elastic Stack 7.x and 8.x

  1. Prerequisites:
    • Trial or Paid account on Elastic Cloud
    • Make sure that the four required analyzer plugins (analysis-icu, analysis-kuromoji, analysis-smartcn and analysis-stempel) are enabled in Elasticsearch (Select your deployment > Edit > Elasticsearch service > Manage user settings and extensions > Extensions.)
  2. Add the following property to elasticsearch.yml: Go to Edit > Elasticsearch service > Manage user settings and extensions > User Settings of your deployment: 
    • cluster.indices.close.enable: true
  3. Save the deployment credentials that Elastic Cloud provides you at the end of the deployment creation process.
    • username: elastic
    • password: <password>
  4. Copy the Endpoint of your Elasticsearch Service from the overview page of your deployment. This will look similar to this: 
    • https://liferay****.gcp.cloud.es.io
    • 9243 is the HTTP port. You can specify it, though it's not needed on DXP 7.3 and 7.4. However, on DXP 7.2, you will need to specify 9343 for the Transport port in the configuration below!
  5. Stop Liferay DXP if it's running
  6. Create com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConfiguration.config in [Liferay-Home]/osgi/configs with the following content:
    • DXP 7.3 and 7.4:
      • networkHostAddresses=["https://liferay***.gcp.cloud.es.io"]
        productionModeEnabled=B"true"
        username="elastic"
        password="<password>"
        authenticationEnabled=B"true"
        httpSSLEnabled=B"true"
        truststorePassword="<password-of-the-JDK-cacerts-file>"
        truststorePath="/PATH/TO/JDK/cacerts"
        truststoreType="jks"
      • networkHostAddresses: This single transport address (which you can derive from your Elasticsearch Endpoint) is the only one you need to set in the connector configuration.
      • truststorePath: points to your JDK's default cacerts file located in JAVA_HOME/lib/security on JDK 11 or JAVA_HOME/jre/lib/security in case of JDK 8. The password defaults to changeit.
      • See also the Security related restrictions of Elastic Cloud
    • DXP 7.2: 
      • clusterName="5b8cfb0167c54ab4afb1bbd157471f77"
        clientTransportSniff=B"false"
        operationMode="REMOTE"
        transportAddresses=["5b8cfb0167c54ab4afb1bbd157471f77.us-west1.gcp.cloud.es.io:9343"]
      • clusterName: Comes from your Elasticsearch Endpoint.
      • clientTransportSniff: Sniffing must be disabled (ref.)
      • transportAddresses: This single transport address (which you can derive from your Elasticsearch Endpoint) is the only one you need to set in the connector configuration. "Deployments hosted on Elasticsearch Service are behind proxies which prevent the transport client from communicating directly with Elasticsearch clusters" (ref.). Remember to use 9343!
  7. (On DXP 7.2 only) Create com.liferay.portal.search.elasticsearch7.configuration.XPackSecurityConfiguration.config in [Liferay-Home]/osgi/configs with the following content: 
    • certificateFormat="PKCS#12"
      sslKeystorePath=""
      sslKeystorePassword=""
      sslTruststorePath="/PATH/TO/cacerts.p12"
      sslTruststorePassword="changeit"
      requiresAuthentication=B"true"
      username="elastic"
      password="<password>"
      transportSSLVerificationMode="certificate"
      transportSSLEnabled=B"true"
    • sslTruststorePath: you can export all entries from your JDK's default cacerts file into a PKCS#12 file with the following command: keytool -importkeystore -srckeystore /PATH/To/JDK/cacerts -srcstorepass changeit -destkeystore /PATH/TO/cacerts.p12 -deststoretype PKCS12 -storepass changeit
    • See also the Security related restrictions of Elastic Cloud
  8. (On DXP 7.2 only) If the Connector to Elasticsearch 7 was not deployed previously, download and the put the LPKG file into [Liferay-Home]/osgi/marketplace.
  9. Start Liferay DXP
  10. Go to the Search admin in the Control Panel and check the connection information (on DXP 7.1+). You will see something like this if everything is working properly:
    • search-admin-connections-7.4-u81-elasticsearch-8.8.1-ec-screenshot-1.png
  11. Execute a full reindex (Reindex search indexes) and also reindex the spell-check indexes (Reindex spell-check dictionaries) through the Index Actions.

Environment - Elastic Stack 6.8.x

Resolution - Elastic Stack 6.8.x

  1. Pre: Make sure that the four required analyzer plugins (analysis-icu, analysis-kuromoji, analysis-smartcn and analysis-stempel) are configured on the deployment customization screen
  2. Add the following property to elasticsearch.yml under the User settings overrides section on the Edit screen of your deployment:
    • cluster.indices.close.enable: true
  3. Save the deployment credentials that Elastic Cloud provides you at the end of the deployment creation process.
    • username: elastic
    • password: <password>
  4. Copy the Deployment Endpoint of your Elasticsearch Service from the overview page of your deployment. This will look similar to this:
  5. Stop Liferay DXP
  6. Create com.liferay.portal.search.elasticsearch6.configuration.ElasticsearchConfiguration.config in [Liferay-Home]/osgi/configs with the following content: 
    • clusterName="5b8cfb0167c54ab4afb1bbd157471f77"
      operationMode="REMOTE"
      transportAddresses=["5b8cfb0167c54ab4afb1bbd157471f77.us-west1.gcp.cloud.es.io:9343"]
      clientTransportSniff=B"false"
    • clusterName: Comes from your Deployment Endpoint.
    • clientTransportSniff: Sniffing must be disabled (ref.)
    • transportAddresses: This single transport address (which you can derive from your Elasticsearch Endpoint) is the only one you need to set in the connector configuration. "Deployments hosted on Elasticsearch Service are behind proxies which prevent the transport client from communicating directly with Elasticsearch clusters" (ref.). Remember to use 9343!
  7. Create com.liferay.portal.search.elasticsearch6.xpack.security.internal.configuration.XPackSecurityConfiguration.config in [Liferay-Home]/osgi/configs with the following content: 
    • certificateFormat="PKCS#12"
      sslKeystorePath=""
      sslKeystorePassword=""
      sslTruststorePath="/home/tibusz/liferay/bundles/cacerts.p12"
      sslTruststorePassword="changeit"
      requiresAuthentication=B"true"
      username="elastic"
      password="<password>"
      transportSSLVerificationMode="certificate"
      transportSSLEnabled=B"true"
    • sslTruststorePath: you can export all entries from your JDK's default cacerts file into a PKCS#12 file with the following command: keytool -importkeystore -srckeystore /PATH/To/JDK/cacerts -srcstorepass changeit -destkeystore /PATH/TO/cacerts.p12 -deststoretype PKCS12 -storepass changeit
    • See also the Security related restrictions of Elastic Cloud
  8. If Liferay Enterprise Search Security was not deployed previously, download and the put the LPKG file into [Liferay-Home]/osgi/marketplace.
  9. Start Liferay DXP
  10. Go to the Search admin in the Control Panel and check the connection information
    • On DXP 7.2: You will see something like this if everything is working properly: 
      • Search Engine Vendor: Elasticsearch, Client Version: 6.8.6, Nodes: 5b8cfb0167c54ab4afb1bbd157471f77: [instance-0000000001 (6.8.10), instance-0000000000 (6.8.10), tiebreaker-0000000002 (6.8.10)]
    • On DXP 7.3: Go to the Connections tab and look at the Active Connections section:
      • DXP-7.3-with-ES-on-EC-Connections.png
  11. Execute a full reindex (Reindex search indexes) and also reindex the spell-check indexes (Reindex spell-check dictionaries) through the Index Actions.

Configuring Enterprise Search Monitoring/X-Pack Monitoring

Configuring Liferay Enterprise Search Monitoring to connect to your hosted Kibana is not possible as the Kibana Service does not support required user settings such as server.basePath and server.rewriteBasePath.

Troubleshooting

Downloading and Importing the server's certificate

Normally, the server's certificates in Azure, AWS and GCP are signed by a trusted CA thus, your JDK's default cacerts file should be enough. In case you experience connection issues (NoNodeAvailableException or similar) try obtaining and importing the server's certificate and use it in the connector configuration in DXP:

  1. Download and import the certificate of your Elasticsearch Deployment
    1. Download the server's certificate in PEM format (for example through your browser's HTTPS connection inspection tool or using openssl):
      • openssl s_client -connect 5b8cfb0167c54ab4afb1bbd157471f77.us-west1.gcp.cloud.es.io:9243 -showcerts
      • The base-64 encoded text for your server gcp.cloud.es.io (between the “-----BEGIN CERTIFICATE-----“ and the “-----END CERTIFICATE -----“) is the certificate of interest.
    2. Copy the certificate text into a file called server.pem
    3. Import the server's certificate into your client's (Liferay DXP) PKCS# 12 format trust store (elastic-certificates.p12, assuming you have created this already): 
      keytool -importcert -keystore elastic-certificates.p12 -storepass <password> -alias <preferred-alias> -file server.pem
  2. Update the connector configurations to use this .p12 file.

Elastic Cloud Restrictions

Not all features and configurations of Elasticsearch and Kibana are supported on Elastic Cloud. Please refer to the article below for details:

https://www.elastic.co/guide/en/cloud/current/ec-restrictions.html

Cloud Provider Restrictions

Depending on the cloud provider of your choice and your subscription method, additional restrictions may apply to your Elasticsearch Service deployments. Please refer to the following resources to learn about which features are impacted:

Please see this article for a technical overview of the Elasticsearch connectors available for Liferay DXP.

*  Please review the Search Engine Compatibility Matrix for the compatible environments.

**  For this article, Elastic Cloud testing was conducted using Google Cloud Platform and the four required analyzer plugins (analysis-icu, analysis-kuromoji, analysis-smartcn and analysis-stempel) on the deployment customization screen.

Was this article helpful?
1 out of 1 found this helpful