Configuring CCR in a Local Follower Data Center

First configure CCR in the remote/leader data center before following the steps below.

The local/follower data center holds Liferay DXP cluster nodes with a read-only connection to the co-located Elasticsearch cluster and a write-only connection to the remote/leader data center’s Elasticsearch cluster.

The example configurations are also provided in full in the CCR configuration reference guide.

Configure the Follower Elasticsearch Cluster

The local Elasticsearch cluster must hold follower (replicated; read-only) indexes and acts as the local search engine co-located Liferay DXP nodes can read from.

important

Securing a CCR Installation: As stated earlier the Elasticsearch clusters should use node certificates signed by the same CA and the security settings of each cluster should match. For other approaches and details, see Elastic’s documentation.

Configure its elasticsearch.yml:

[Follower Elasticsearch Home]/config/elasticsearch.yml

cluster.name: LiferayElasticsearchCluster_FOLLOWER
node.name: es-follower-node-1

http.port: 9201
transport.port: 9301

xpack.security.enabled: true

### TLS/SSL settings for Transport layer
xpack.security.transport.ssl.enabled: true
xpack.security.transport.ssl.keystore.path: certs/elastic-nodes.p12
xpack.security.transport.ssl.keystore.password: liferay
xpack.security.transport.ssl.truststore.path: certs/elastic-nodes.p12
xpack.security.transport.ssl.truststore.password: liferay
xpack.security.transport.ssl.verification_mode: certificate

## TLS/SSL settings for HTTP layer
xpack.security.http.ssl.enabled: true
xpack.security.http.ssl.keystore.path: certs/elastic-nodes.p12
xpack.security.http.ssl.keystore.password: liferay
xpack.security.http.ssl.truststore.path: certs/elastic-nodes.p12
xpack.security.http.ssl.truststore.password: liferay

# For Kibana
xpack.monitoring.collection.enabled: true

To use the security settings (xpack.security...) you must set up passwords and obtain node certificates.

Start the server. If you’re in the root of the server directory, execute
```
./bin/elasticssearch
```
If you’re just trying this out and don’t yet have the proper license, start an Elasticsearch trial:
```
POST /_license/start_trial?acknowledge=true
```

Configure the Local Liferay DXP Cluster Node

tip

If testing locally, configure Tomcat to use different ports than your remote DXP node. Use 9080 as the HTTP port, 9443 as the redirect port, and 9005 as the shutdown port to follow this example setup (change the server ports in [Liferay Home]/tomcat-[version]/conf/server.xml).

Copy the Elasticsearch connection configuration files from the remote DXP cluster node’s osgi/configs folder, into the corresponding folder on the local DXP cluster node.

For Liferay DXP 7.3, this includes *ElasticsearchConnectionConfiguration-remote.config and *ElasticsearchConfiguration.config.

important

The remoteClusterConnectionId value in the ElasticsearchConfiguration.config must match the connectionId in the ElasticsearchConnectionConfiguration-remote.config file.

For Liferay DXP 7.1 and 7.2, this includes *ElasticsearchConfiguration.config and *XPackSecurityConfiguration.config.

Once these files are provided, the write connection for the local DXP cluster node is configured.
Now configure the read-only connection to the local Elasticsearch server with the follower indexes.

For Liferay DXP 7.3, provide a configuration file to Liferay Home/osgi/configs named com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConnectionConfiguration-ccr.config.

Give it these contents:
```
active=B"true"
connectionId="ccr"
username="elastic"
password="liferay"
authenticationEnabled=B"true"
httpSSLEnabled=B"true"
networkHostAddresses=["https://localhost:9201"]
truststorePassword="liferay"
truststorePath="/PATH/TO/elastic-nodes.p12"
truststoreType="pkcs12"
```
For Liferay DXP 7.1 and 7.2, provide a configuration file to Liferay Home/osgi/configs named com.liferay.portal.search.elasticsearch.cross.cluster.replication.internal.configuration.ElasticsearchConnectionConfiguration-ccr.config.

warning

On Liferay 7.2, do not deploy the configuration file for the CCR connection (e.g., ElasticsearchConnectionConfiguration-ccr.config) simultaneously with the LES Cross-Cluster Replication LPKG’s initial deployment. There’s a known bug (LPS-127821) that breaks Liferay’s search functionality if the configuration file is deployed before the module is fully started. If you’ve already encounterd this, see Troubleshooting Cross-Cluster Replication for the workaround.
```
clusterName="LiferayElasticsearchCluster_FOLLOWER"
connectionId="ccr"
username="elastic"
password="liferay"
authenticationEnabled=B"true"
transportSSLEnabled=B"true"
networkHostAddress="https://localhost:9201"
transportAddresses=["localhost:9301"]
sslTruststorePassword="liferay"
sslTruststorePath="/PATH/TO/elastic-nodes.p12"
certificateFormat="pkcs12"
sslKeystorePassword="liferay"
sslKeystorePath="/PATH/TO/elastic-nodes.p12"
```
You can use any suffix (-ccr in this example) for the configuration file name, but for consistency you should make it identical to the connectionId property in the configuration.
Start the Liferay DXP cluster node.

Now the connection is configured.

All that’s left is to enable and configure CCR itself.

Configure the Cross-Cluster Replication Module

The LES Cross-Cluster Replication module triggers the following of the leader cluster and the initial replication of all indexes from the leader cluster to the follower cluster. Triggering follow and replication relies on enabling the CCR functionality in the System Settings UI, and not via configuration file (.config). Configure CCR from any Liferay DXP node in either data center:

Open the Global Menu and navigate to Control Panel → System Settings. Open the Search category.
Open Cross-Cluster Replication.
Check the box for Read from Local Clusters.
Set one value in Local Cluster Configurations localhost:9080,ccr.

important

Never set the value to the remote data center here (in the example, it would be localhost:8080,remote). Setting this would cause follower indexes to be created in the remote cluster, where leader indexes of the same name already reside.

This defines the connections that should be read-only. In human language, each entry here is saying “the Liferay server at this address (localhost:9080) reads from the Elasticsearch connection with this name (ccr in this example).”
Click Update.

In a production setup, you may want to set a different transport address for the remote Elasticsearch cluster (this example used the default) and/or exclude some indexes from being replicated to the follower Elasticsearch cluster. There are configuration fields for those purposes:

Remote Cluster Seed Node Transport Address: The transport address of a node in the remote cluster to be used for establishing a connection between the remote and local cluster. Defaults to localhost:9300.

Excluded Indexes: Enter the index names to be excluded from cross-cluster replication. Indexes starting with a period (.) are always excluded. By default, all indexes in the remote cluster are replicated to the local cluster. This setting is ignored if Automatic Replication is not enabled.

Automatic Replication Enabled: Enable or disable automatic creation of follower indexes in the local Elasticsearch clusters when Read from Local Clusters is enabled. Disable this setting if replication is managed manually through Elasticsearch. Defaults to enabled.

Log messages appear, indicating successful index replication and that the read connection is enabled

2021-01-22 02:15:11.112 INFO  [liferay/configuration-1][CrossClusterReplicationConfigurationModelListener:163] Creating follower indexes
2021-01-22 02:15:12.864 INFO  [liferay/configuration-1][CrossClusterReplicationConfigurationModelListener:70] Read operations from local clusters are enabled

Once the connections are configured and the indexes replicated, verify the system is working properly.

Verify the Setup

On the follower DXP cluster node, navigate to Control Panel → Configuration → Search. On Liferay DXP 7.2, you must also click the Connections tab. Your connections look like this: