Cross-cluster replication API

Introduced 1.1

Initiate replication of an index from the leader cluster to the follower cluster. Send this request to the follower cluster.

Request

Specify the following options:

Example response

  1. {
  2.    "acknowledged": true
  3. }

Stop replication

Introduced 1.1

Terminates replication and converts the follower index to a standard index. Send this request to the follower cluster.

Request

  1. POST /_plugins/_replication/<follower-index>/_stop
  2. {}

Example response

  1. {
  2.    "acknowledged": true
  3. }

Pause replication

Introduced 1.1

Pauses replication of the leader index. Send this request to the follower cluster.

Request

  1. POST /_plugins/_replication/<follower-index>/_pause 
  2. {}

You can’t resume replication after it’s been paused for more than 12 hours. You must stop replication, delete the follower index, and restart replication of the leader.

Example response

  1. {
  2.    "acknowledged": true
  3. }

Introduced 1.1

Request

  1. POST /_plugins/_replication/<follower-index>/_resume
  2. {}

Example response

Get replication status

Introduced 1.1

Gets the status of index replication. Possible statuses are SYNCING, BOOTSTRAPING, PAUSED, and REPLICATION NOT IN PROGRESS. Use the syncing details to measure replication lag. Send this request to the follower cluster.

Request

  1. GET /_plugins/_replication/<follower-index>/_status

Example response

  1. {
  2.   "status" : "SYNCING",
  3.   "reason" : "User initiated",
  4.   "leader_alias" : "my-connection-name",
  5.   "leader_index" : "leader-01",
  6.   "follower_index" : "follower-01",
  7.   "syncing_details" : {
  8.     "leader_checkpoint" : 19,
  9.     "follower_checkpoint" : 19,
  10.     "seq_no" : 0
  11.   }

To include shard replication details in the response, add the &verbose=true parameter.

The leader and follower checkpoint values begin as negative integers and reflect the shard count (-1 for one shard, -5 for five shards, and so on). The values increment toward positive integers with each change that you make. For example, when you make a change on the leader index, the leader_checkpoint becomes 0. The follower_checkpoint is initially still -1 until the follower index pulls the change from the leader, at which point it increments to 0. If the values are the same, it means the indexes are fully synced.

Get leader cluster stats

Introduced 1.1

Gets information about replicated leader indexes on a specified cluster.

Request

  1. GET /_plugins/_replication/leader_stats

Example response

  1. {
  2.    "num_replicated_indices": 2,
  3.    "operations_read": 15,
  4.    "translog_size_bytes": 1355,
  5.    "operations_read_lucene": 0,
  6.    "operations_read_translog": 15,
  7.    "total_read_time_lucene_millis": 0,
  8.    "total_read_time_translog_millis": 659,
  9.    "bytes_read": 1000,
  10.    "index_stats":{
  11.       "leader-index-1":{
  12.          "operations_read": 7,
  13.          "translog_size_bytes": 639,
  15.          "operations_read_translog": 7,
  16.          "total_read_time_lucene_millis": 0,
  17.          "total_read_time_translog_millis": 353,
  18.          "bytes_read":466
  19.       },
  20.       "leader-index-2":{
  21.          "operations_read": 8,
  22.          "translog_size_bytes": 716,
  23.          "operations_read_lucene": 0,
  24.          "operations_read_translog": 8,
  25.          "total_read_time_lucene_millis": 0,
  26.          "total_read_time_translog_millis": 306,
  27.          "bytes_read": 534
  28.       }
  29.    }
  30. }

Introduced 1.1

Gets information about follower (syncing) indexes on a specified cluster.

Request

  1. GET /_plugins/_replication/follower_stats

Example response

  1. {
  2.    "num_syncing_indices": 2,
  3.    "num_bootstrapping_indices": 0,
  4.    "num_paused_indices": 0,
  5.    "num_failed_indices": 0,
  6.    "num_shard_tasks": 2,
  7.    "num_index_tasks": 2,
  8.    "operations_written": 3,
  9.    "operations_read": 3,
  10.    "failed_read_requests": 0,
  11.    "throttled_read_requests": 0,
  12.    "failed_write_requests": 0,
  13.    "throttled_write_requests": 0,
  14.    "follower_checkpoint": 1,
  15.    "leader_checkpoint": 1,
  16.    "total_write_time_millis": 2290,
  17.    "index_stats":{
  18.       "follower-index-1":{
  19.          "operations_written": 2,
  20.          "operations_read": 2,
  21.          "failed_read_requests": 0,
  22.          "throttled_read_requests": 0,
  23.          "failed_write_requests": 0,
  24.          "throttled_write_requests": 0,
  25.          "follower_checkpoint": 1,
  26.          "leader_checkpoint": 1,
  27.          "total_write_time_millis": 1355
  28.       },
  29.          "operations_written": 1,
  30.          "operations_read": 1,
  31.          "failed_read_requests": 0,
  32.          "throttled_read_requests": 0,
  33.          "failed_write_requests": 0,
  34.          "throttled_write_requests": 0,
  35.          "follower_checkpoint": 0,
  36.          "leader_checkpoint": 0,
  37.          "total_write_time_millis": 935
  38.       }
  39.    }
  40. }

Get auto-follow stats

Introduced 1.1

Request

Example response

  1. {
  3.    "num_failed_start_replication": 0,
  4.    "num_failed_leader_calls": 0,
  5.    "failed_indices":[
  7.    ],
  8.    "autofollow_stats":[
  9.       {
  10.          "name":"my-replication-rule",
  11.          "pattern":"movies*",
  12.          "num_success_start_replication": 2,
  13.          "num_failed_start_replication": 0,
  14.          "num_failed_leader_calls": 0,
  15.          "failed_indices":[
  17.          ]
  18.       }
  19.    ]
  20. }

Update settings

Introduced 1.1

Updates settings on the follower index.

Request

  1. PUT /_plugins/_replication/<follower-index>/_update
  2. {
  3.    "settings":{
  4.       "index.number_of_shards": 4,
  5.       "index.number_of_replicas": 2
  6.    }
  7. }

Example response

  1. {
  2.    "acknowledged": true
  3. }

Introduced 1.1

Automatically starts replication on indexes matching a specified pattern. If a new index on the leader cluster matches the pattern, OpenSearch automatically creates a follower index and begins replication. You can also use this API to update existing replication rules.

Send this request to the follower cluster.

Make sure to note the names of all auto-follow patterns after you create them. The replication plugin currently does not include an API operation to retrieve a list of existing patterns.

Request

  1. POST /_plugins/_replication/_autofollow
  2. {
  3.    "leader_alias" : "<connection-alias-name>",
  4.    "name": "<auto-follow-pattern-name>",
  5.    "pattern": "<pattern>",
  6.    "use_roles":{
  7.       "leader_cluster_role": "<role-name>",
  8.       "follower_cluster_role": "<role-name>"
  9.    }
  10. }

Specify the following options:

Example response

  1. {
  2.    "acknowledged": true
  3. }

Delete replication rule

Introduced 1.1

Deletes the specified replication rule. This operation prevents any new indexes from being replicated but does not stop existing replication that the rule has already initiated. Replicated indexes remain read-only until you stop replication.

Request

  1. DELETE /_plugins/_replication/_autofollow
  2. {
  3.    "leader_alias" : "<connection-alias-name>",
  4.    "name": "<auto-follow-pattern-name>",
  5. }

Specify the following options:

Example response