Enable cross cluster search

Cross cluster search is a RESTful API-only feature that allows you to search across multiple Elasticsearch clusters with a single query.

To run queries against other clusters using cross cluster search, you can configure existing Elasticsearch clusters.

Cluster settings are automatically maintained and updated when cluster topologies change. For example, all connected clusters are updated when:

  • A cluster is deleted
  • A node is added or removed from a cluster
  • An IP address changes

Before you begin

To enable cross cluster search, you must meet the following criteria.

  • To access the RESTful API for Elastic Cloud Enterprise, you must have a bearer token.
  • All clusters must be in the same region and owned by the same user.
  • All Elasticsearch clusters must be version 6.0 or later.

For more information about cross cluster search in Elasticsearch, refer to the Elasticsearch documentation.

Enable cross cluster search on your cluster

To configure your cluster for cross cluster search, run the following command:

curl --request PUT \
  --url https://<endpoint>/clusters/elasticsearch/<clusterID>/ccs/settings \
  --header 'authorization: Bearer <token>' \
  --header 'content-type: application/json' \
  --data '{
      "remote_clusters": {
        "alias1": {
          "cluster_id": "<clusterID>",
          "skip_unavailable": true
        },
        "alias2": {
          "cluster_id": "<clusterID>",
          "skip_unavailable": false
        }
       }
     }'

Admin console endpoint for the API

ID of the cluster you want to configure

Bearer token for authentication

Cluster aliases must contain only letters, numbers, dashes (-), or underscores (_). For example, alias1 and alias2

ID of the cluster that you want to connect

ID of another cluster that you want to connect

When the cluster is unavailable, the skip_unavailable parameter defines the search behavior

For more information about skipping disconnected clusters, refer to the Elasticsearch documentation.

Tip

When cross cluster search is already configured on a cluster, the PUT request replaces the existing configuration with the new settings.

Important

Other cross cluster search settings that are exposed by Elasticsearch are managed by Elastic Cloud Enterprise. Do not change these settings.

To retrieve a cross cluster search configuration, run the following command:

 curl --request GET \
   --url https://<endpoint>/clusters/elasticsearch/<clusterID>/ccs/settings \
   --header 'authorization: Bearer <token>' \
   --header 'content-type: application/json'

The configuration returns the data in the same format as the PUT request.

Additionally, when the cluster ID is provided, the ccs endpoint populates a list of the cross cluster search configurations that a cluster belongs to:

 curl --request GET \
   --url https://<endpoint>/clusters/elasticsearch/<clusterID>/ccs \
   --header 'authorization: Bearer <token>' \
   --header 'content-type: application/json'

The response contains the list of cluster IDs:

{
  "ccs_clusters": ["1cdf414b51d84d789df9ebd942b1b5d4"]
}

Use the cluster IDs to retrieve the cross cluster configuration, where <clusterID> is set as the remote.