Cross-Cluster Replication API
Use these replication operations to programmatically manage cross-cluster replication.
Table of contents
Start replication
Introduced 1.1
Initiate replication of an index from the leader cluster to the follower cluster. Send this request to the follower cluster.
Endpoints
PUT /_plugins/_replication/{follower-index}/_start
Request body fields
The following table lists the available request body fields.
| Field | Data type | Description | Required |
|---|---|---|---|
leader_alias | String | The name of the cross-cluster connection. You define this alias when you set up a cross-cluster connection. | Yes |
leader_index | String | The index on the leader cluster that you want to replicate. | Yes |
use_roles | Object | The roles to use for all subsequent backend replication tasks between the indexes. Specify a leader_cluster_role and follower_cluster_role. See Map the leader and follower cluster roles. | If Security plugin is enabled |
Example request
PUT /_plugins/_replication/follower-01/_start
{
"leader_alias": "my-connection-alias",
"leader_index": "leader-01",
"use_roles": {
"leader_cluster_role": "cross_cluster_replication_leader_full_access",
"follower_cluster_role": "cross_cluster_replication_follower_full_access"
}
}
Example response
{
"acknowledged": true
}
Stop replication
Introduced 1.1
Terminates replication and converts the follower index to a standard index. Send this request to the follower cluster.
Endpoints
POST /_plugins/_replication/{follower-index}/_stop
Example request
POST /_plugins/_replication/follower-01/_stop
{}
Example response
{
"acknowledged": true
}
Pause replication
Introduced 1.1
Pauses replication of the leader index. Send this request to the follower cluster.
Endpoints
POST /_plugins/_replication/{follower-index}/_pause
Example request
POST /_plugins/_replication/follower-01/_pause
{}
You can’t resume replication after it’s been paused longer than the retention lease period. To recover, use force-resume, which restores the follower index from a snapshot of the leader.
Example response
{
"acknowledged": true
}
Resume replication
Introduced 1.1
Resumes replication of the leader index. Send this request to the follower cluster.
Endpoints
POST /_plugins/_replication/{follower-index}/_resume
Request body fields
The following table lists the available request body fields.
| Field | Data type | Description | Required |
|---|---|---|---|
force_resume | Boolean | When set to true, performs a stop-delete-start cycle to restore the follower index from the leader when retention leases have expired. Use this when replication has been paused for more than 12 hours and a normal resume fails. For more information, see Force resume replication. Default is false. | No |
Example request
POST /_plugins/_replication/follower-01/_resume
{}
Example response
{
"acknowledged": true
}
Error responses
The following table describes common error responses for the resume operation.
| Status code | Error | Description |
|---|---|---|
| 404 | Retention lease doesn't exist. Use force_resume=true to restore from snapshot. | The retention lease has expired and force_resume was not set to true. Retry the request with "force_resume": true. |
| 400 | Replication is not in PAUSED state | Force resume can only be used when replication is paused. Check the replication status first. |
| 500 | Failed to stop replication | The internal stop operation failed. Verify cluster health and retry. |
| 500 | Failed to delete follower index | The follower index could not be deleted after stopping replication. Manual cleanup may be required. |
| 500 | Failed to start replication | The internal start operation failed after the follower was deleted. You may need to manually start replication again. |
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.
Endpoints
GET /_plugins/_replication/{follower-index}/_status
Example request
GET /_plugins/_replication/follower-01/_status
Example response
{
"status" : "SYNCING",
"reason" : "User initiated",
"leader_alias" : "my-connection-name",
"leader_index" : "leader-01",
"follower_index" : "follower-01",
"syncing_details" : {
"leader_checkpoint" : 19,
"follower_checkpoint" : 19,
"seq_no" : 0
}
}
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.
Endpoints
GET /_plugins/_replication/leader_stats
Example request
GET /_plugins/_replication/leader_stats
Example response
{
"num_replicated_indices": 2,
"operations_read": 15,
"translog_size_bytes": 1355,
"operations_read_lucene": 0,
"operations_read_translog": 15,
"total_read_time_lucene_millis": 0,
"total_read_time_translog_millis": 659,
"bytes_read": 1000,
"index_stats":{
"leader-index-1":{
"operations_read": 7,
"translog_size_bytes": 639,
"operations_read_lucene": 0,
"operations_read_translog": 7,
"total_read_time_lucene_millis": 0,
"total_read_time_translog_millis": 353,
"bytes_read":466
},
"leader-index-2":{
"operations_read": 8,
"translog_size_bytes": 716,
"operations_read_lucene": 0,
"operations_read_translog": 8,
"total_read_time_lucene_millis": 0,
"total_read_time_translog_millis": 306,
"bytes_read": 534
}
}
}
Get follower cluster stats
Introduced 1.1
Gets information about follower (syncing) indexes on a specified cluster.
Endpoints
GET /_plugins/_replication/follower_stats
Example request
GET /_plugins/_replication/follower_stats
Example response
{
"num_syncing_indices": 2,
"num_bootstrapping_indices": 0,
"num_paused_indices": 0,
"num_failed_indices": 0,
"num_shard_tasks": 2,
"num_index_tasks": 2,
"operations_written": 3,
"operations_read": 3,
"failed_read_requests": 0,
"throttled_read_requests": 0,
"failed_write_requests": 0,
"throttled_write_requests": 0,
"follower_checkpoint": 1,
"leader_checkpoint": 1,
"total_write_time_millis": 2290,
"index_stats":{
"follower-index-1":{
"operations_written": 2,
"operations_read": 2,
"failed_read_requests": 0,
"throttled_read_requests": 0,
"failed_write_requests": 0,
"throttled_write_requests": 0,
"follower_checkpoint": 1,
"leader_checkpoint": 1,
"total_write_time_millis": 1355
},
"follower-index-2":{
"operations_written": 1,
"operations_read": 1,
"failed_read_requests": 0,
"throttled_read_requests": 0,
"failed_write_requests": 0,
"throttled_write_requests": 0,
"follower_checkpoint": 0,
"leader_checkpoint": 0,
"total_write_time_millis": 935
}
}
}
Get auto-follow stats
Introduced 1.1
Gets information about auto-follow activity and any replication rules configured on the specified cluster.
Endpoints
GET /_plugins/_replication/autofollow_stats
Example request
GET /_plugins/_replication/autofollow_stats
Example response
{
"num_success_start_replication": 2,
"num_failed_start_replication": 0,
"num_failed_leader_calls": 0,
"failed_indices":[
],
"autofollow_stats":[
{
"name":"my-replication-rule",
"pattern":"movies*",
"num_success_start_replication": 2,
"num_failed_start_replication": 0,
"num_failed_leader_calls": 0,
"failed_indices":[
]
}
]
}
Update settings
Introduced 1.1
Updates settings on the follower index.
Endpoints
PUT /_plugins/_replication/{follower-index}/_update
Example request
PUT /_plugins/_replication/follower-01/_update
{
"settings": {
"index.number_of_shards": 4,
"index.number_of_replicas": 2
}
}
Example response
{
"acknowledged": true
}
Create replication rule
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.
Endpoints
POST /_plugins/_replication/_autofollow
Request body fields
The following table lists the available request body fields.
| Field | Data type | Description | Required |
|---|---|---|---|
leader_alias | String | The name of the cross-cluster connection. You define this alias when you set up a cross-cluster connection. | Yes |
name | String | A name for the auto-follow pattern. | Yes |
pattern | String | An array of index patterns to match against indexes in the specified leader cluster. Supports wildcard characters. For example, leader-*. | Yes |
use_roles | Object | The roles to use for all subsequent backend replication tasks between the indexes. Specify a leader_cluster_role and follower_cluster_role. See Map the leader and follower cluster roles. | If Security plugin is enabled |
Example request
POST /_plugins/_replication/_autofollow
{
"leader_alias": "my-connection-alias",
"name": "my-replication-rule",
"pattern": "leader-*",
"use_roles": {
"leader_cluster_role": "cross_cluster_replication_leader_full_access",
"follower_cluster_role": "cross_cluster_replication_follower_full_access"
}
}
Example response
{
"acknowledged": true
}
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.
Send this request to the follower cluster.
Endpoints
DELETE /_plugins/_replication/_autofollow
Request body fields
The following table lists the available request body fields.
| Field | Data type | Description | Required |
|---|---|---|---|
leader_alias | String | The name of the cross-cluster connection. You define this alias when you set up a cross-cluster connection. | Yes |
name | String | The name of the pattern. | Yes |
Example request
DELETE /_plugins/_replication/_autofollow
{
"leader_alias": "my-connection-alias",
"name": "my-replication-rule"
}
Example response
{
"acknowledged": true
}