Create follower API

edit

This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.

Creates a follower index.

Description

edit

This API creates a new follower index that is configured to follow the referenced leader index. When this API returns, the follower index exists, and cross-cluster replication starts replicating operations from the leader index to the follower index.

Request

edit
PUT /<follower_index>/_ccr/follow
{
  "remote_cluster" : "<remote_cluster>",
  "leader_index" : "<leader_index>"
}

Path Parameters

edit
follower_index (required)
(string) the name of the follower index

Request Body

edit
remote_cluster (required)
(string) the remote cluster containing the leader index
leader_index (required)
(string) the name of the index in the leader cluster to follow
max_read_request_operation_count
(integer) the maximum number of operations to pull per read from the remote cluster
max_outstanding_read_requests
(long) the maximum number of outstanding reads requests from the remote cluster
max_read_request_size
(byte value) the maximum size in bytes of per read of a batch of operations pulled from the remote cluster
max_write_request_operation_count
(integer) the maximum number of operations per bulk write request executed on the follower
max_write_request_size
(byte value) the maximum total bytes of operations per bulk write request executed on the follower
max_outstanding_write_requests
(integer) the maximum number of outstanding write requests on the follower
max_write_buffer_count
(integer) the maximum number of operations that can be queued for writing; when this limit is reached, reads from the remote cluster will be deferred until the number of queued operations goes below the limit
max_write_buffer_size
(byte value) the maximum total bytes of operations that can be queued for writing; when this limit is reached, reads from the remote cluster will be deferred until the total bytes of queued operations goes below the limit
max_retry_delay
(time value) the maximum time to wait before retrying an operation that failed exceptionally; an exponential backoff strategy is employed when retrying
read_poll_timeout
(time value) the maximum time to wait for new operations on the remote cluster when the follower index is synchronized with the leader index; when the timeout has elapsed, the poll for operations will return to the follower so that it can update some statistics, and then the follower will immediately attempt to read from the leader again

Authorization

edit

If the Elasticsearch security features are enabled, you must have write, monitor, and manage_follow_index index privileges for the follower index. You must have read and monitor index privileges for the leader index. You must also have manage_ccr cluster privileges on the cluster that contains the follower index. For more information, see Security privileges.

Example

edit

This example creates a follower index named follower_index:

PUT /follower_index/_ccr/follow
{
  "remote_cluster" : "remote_cluster",
  "leader_index" : "leader_index",
  "max_read_request_operation_count" : 1024,
  "max_outstanding_read_requests" : 16,
  "max_read_request_size" : "1024k",
  "max_write_request_operation_count" : 32768,
  "max_write_request_size" : "16k",
  "max_outstanding_write_requests" : 8,
  "max_write_buffer_count" : 512,
  "max_write_buffer_size" : "512k",
  "max_retry_delay" : "10s",
  "read_poll_timeout" : "30s"
}

The API returns the following result:

{
  "follow_index_created" : true,
  "follow_index_shards_acked" : true,
  "index_following_started" : true
}