Tutorial: Set up cross-cluster replication

Use this guide to set up cross-cluster replication (CCR) between clusters in two datacenters. Replicating your data across datacenters provides several benefits:

  • Brings data closer to your users or application server to reduce latency and response time
  • Provides your mission-critical applications with the tolerance to withstand datacenter or region outages

In this guide, you’ll learn how to:

  • Configure a remote cluster with a leader index
  • Create a follower index on a local cluster
  • Create an auto-follow pattern to automatically follow time series indices that are periodically created in a remote cluster

You can manually create follower indices to replicate specific indices on a remote cluster, or configure auto-follow patterns to replicate rolling time series indices.

Your browser does not support the video tag.

Prerequisites

To complete this tutorial, you need:

  • A license on both clusters that includes cross-cluster replication. Activate a free 30-day trial.
  • The read_ccr cluster privilege and monitor and read privileges for the leader index on the remote cluster. Configure remote cluster privileges.
  • The manage_ccr cluster privilege and monitor, read, write and manage_follow_index privileges to configure remote clusters and follower indices on the local cluster. Configure local cluster privileges.
  • An index on the remote cluster that contains the data you want to replicate. This tutorial uses the sample eCommerce orders data set. Load sample data.

Connect to a remote cluster

To replicate an index on a remote cluster (Cluster A) to a local cluster (Cluster B), you configure Cluster A as a remote on Cluster B.

ClusterA contains the leader index and ClusterB contains the follower index

To configure a remote cluster from Stack Management in Kibana:

  1. Select Remote Clusters from the side navigation.
  2. Specify the IP address or host name of the remote cluster (ClusterB), followed by the transport port of the remote cluster (defaults to 9300). For example, 192.168.1.1:9300.

The Add remote clusters page in Kibana

API example

Use the cluster update settings API to add a remote cluster:

  1. PUT /_cluster/settings
  2. {
  3. "persistent" : {
  4. "cluster" : {
  5. "remote" : {
  6. "leader" : {
  7. "seeds" : [
  8. "127.0.0.1:9300"
  9. ]
  10. }
  11. }
  12. }
  13. }
  14. }

Specifies the hostname and transport port of a seed node in the remote cluster.

You can verify that the local cluster is successfully connected to the remote cluster.

  1. GET /_remote/info

The API will respond by showing that the local cluster is connected to the remote cluster.

  1. {
  2. "leader" : {
  3. "seeds" : [
  4. "127.0.0.1:9300"
  5. ],
  6. "connected" : true,
  7. "num_nodes_connected" : 1,
  8. "max_connections_per_cluster" : 3,
  9. "initial_connect_timeout" : "30s",
  10. "skip_unavailable" : false,
  11. "mode" : "sniff"
  12. }
  13. }

This shows the local cluster is connected to the remote cluster with cluster alias leader

This shows the number of nodes in the remote cluster the local cluster is connected to.

Enable soft deletes on leader indices

To follow an index, it must have been created with soft deletes enabled. If the index doesn’t have soft deletes enabled, you must reindex it and use the new index as the leader index. Soft deletes are enabled by default on new indices created with Elasticsearch 7.0.0 and later.

Create a follower index to replicate a specific index

When you create a follower index, you reference the remote cluster and the leader index in your remote cluster.

To create a follower index from Stack Management in Kibana:

  1. Select Cross-Cluster Replication in the side navigation and choose the Follower Indices tab.
  2. Choose the cluster (ClusterA) containing the leader index you want to replicate.
  3. Enter the name of the leader index, which is kibana_sample_data_ecommerce if you are following the tutorial.
  4. Enter a name for your follower index, such as follower-kibana-sample-data.

Adding a follower index named server-metrics in Kibana

Elasticsearch initializes the follower using the remote recovery process, which transfers the existing Lucene segment files from the leader index to the follower index. The index status changes to Paused. When the remote recovery process is complete, the index following begins and the status changes to Active.

When you index documents into your leader index, Elasticsearch replicates the documents in the follower index.

The Cross-Cluster Replication page in Kibana

API example

Use the create follower API to create follower indices. When you create a follower index, you must reference the remote cluster and the leader index that you created in the remote cluster.

When initiating the follower request, the response returns before the remote recovery process completes. To wait for the process to complete, add the wait_for_active_shards parameter to your request.

  1. PUT /server-metrics-follower/_ccr/follow?wait_for_active_shards=1
  2. {
  3. "remote_cluster" : "leader",
  4. "leader_index" : "server-metrics"
  5. }

Use the get follower stats API to inspect the status of replication

Create an auto-follow pattern to replicate time series indices

You use auto-follow patterns to automatically create new followers for rolling time series indices. Whenever the name of a new index on the remote cluster matches the auto-follow pattern, a corresponding follower index is added to the local cluster.

An auto-follow pattern specifies the remote cluster you want to replicate from, and one or more index patterns that specify the rolling time series indices you want to replicate.

To create an auto-follow pattern from Stack Management in Kibana:

  1. Select Cross Cluster Replication in the side navigation and choose the Auto-follow patterns tab.
  2. Enter a name for the auto-follow pattern, such as beats.
  3. Choose the remote cluster that contains the index you want to replicate, which in the example scenario is Cluster A.
  4. Enter one or more index patterns that identify the indices you want to replicate from the remote cluster. For example, enter metricbeat-* packetbeat-* to automatically create followers for Metricbeat and Packetbeat indices.
  5. Enter follower- as the prefix to apply to the names of the follower indices so you can more easily identify replicated indices.

As new indices matching these patterns are created on the remote, Elasticsearch automatically replicates them to local follower indices.

The Auto-follow patterns page in Kibana

API example

Use the create auto-follow pattern API to configure auto-follow patterns.

  1. PUT /_ccr/auto_follow/beats
  2. {
  3. "remote_cluster" : "leader",
  4. "leader_index_patterns" :
  5. [
  6. "metricbeat-*",
  7. "packetbeat-*"
  8. ],
  9. "follow_index_pattern" : "{{leader_index}}-copy"
  10. }

Automatically follow new Metricbeat indices.

Automatically follow new Packetbeat indices.

The name of the follower index is derived from the name of the leader index by adding the suffix -copy to the name of the leader index.