honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOCS] Reformat CCR APIs to use new API format (#43952)

This commit is contained in:
Lisa Cawley 2019-07-04 08:22:17 -07:00 committed by lcawl
parent aeb3c1fd1b
commit a030e3e513
12 changed files with 428 additions and 346 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
docs/reference/ccr/apis/auto-follow/delete-auto-follow-pattern.asciidoc
View File

@ -8,12 +8,8 @@
Delete auto-follow patterns. Delete auto-follow patterns.
==== Description [[ccr-delete-auto-follow-pattern-request]]
==== {api-request-title}
This API deletes a configured collection of
{stack-ov}/ccr-auto-follow.html[auto-follow patterns].
==== Request
////////////////////////// //////////////////////////
@ -42,17 +38,28 @@ DELETE /_ccr/auto_follow/<auto_follow_pattern_name>
// CONSOLE // CONSOLE
// TEST[s/<auto_follow_pattern_name>/my_auto_follow_pattern/] // TEST[s/<auto_follow_pattern_name>/my_auto_follow_pattern/]
==== Path Parameters [[ccr-delete-auto-follow-pattern-prereqs]]
`auto_follow_pattern_name` (required):: ==== {api-prereq-title}
(string) specifies the auto-follow pattern collection to delete
==== Authorization * If the {es} {security-features} are enabled, you must have `manage_ccr` cluster
If the {es} {security-features} are enabled, you must have `manage_ccr` cluster
privileges on the cluster that contains the follower index. For more information, privileges on the cluster that contains the follower index. For more information,
see {stack-ov}/security-privileges.html[Security privileges]. see {stack-ov}/security-privileges.html[Security privileges].
==== Example [[ccr-delete-auto-follow-pattern-desc]]
==== {api-description-title}
This API deletes a configured collection of
{stack-ov}/ccr-auto-follow.html[auto-follow patterns].
[[ccr-delete-auto-follow-pattern-path-parms]]
==== {api-path-parms-title}
`<auto_follow_pattern_name>` (Required)::
(string) Specifies the auto-follow pattern collection to delete.
[[ccr-delete-auto-follow-pattern-examples]]
==== {api-examples-title}
This example deletes an auto-follow pattern collection named This example deletes an auto-follow pattern collection named
`my_auto_follow_pattern`: `my_auto_follow_pattern`:

36
docs/reference/ccr/apis/auto-follow/get-auto-follow-pattern.asciidoc
View File

@ -8,12 +8,8 @@
Get auto-follow patterns. Get auto-follow patterns.
==== Description [[ccr-get-auto-follow-pattern-request]]
==== {api-request-title}
This API gets configured {stack-ov}/ccr-auto-follow.html[auto-follow patterns].
This API will return the specified auto-follow pattern collection.
==== Request
////////////////////////// //////////////////////////
@ -56,19 +52,29 @@ GET /_ccr/auto_follow/<auto_follow_pattern_name>
// CONSOLE // CONSOLE
// TEST[s/<auto_follow_pattern_name>/my_auto_follow_pattern/] // TEST[s/<auto_follow_pattern_name>/my_auto_follow_pattern/]
==== Path Parameters [[ccr-get-auto-follow-pattern-prereqs]]
`auto_follow_pattern_name`:: ==== {api-prereq-title}
(string) specifies the auto-follow pattern collection that you want to
retrieve; if you do not specify a name, the API returns information for all
collections
==== Authorization * If the {es} {security-features} are enabled, you must have `manage_ccr` cluster
If the {es} {security-features} are enabled, you must have `manage_ccr` cluster
privileges on the cluster that contains the follower index. For more information, privileges on the cluster that contains the follower index. For more information,
see {stack-ov}/security-privileges.html[Security privileges]. see {stack-ov}/security-privileges.html[Security privileges].
==== Example [[ccr-get-auto-follow-pattern-desc]]
==== {api-description-title}
This API gets configured {stack-ov}/ccr-auto-follow.html[auto-follow patterns].
This API will return the specified auto-follow pattern collection.
[[ccr-get-auto-follow-pattern-path-parms]]
==== {api-path-parms-title}
`<auto_follow_pattern_name>` (Optional)::
(string) Specifies the auto-follow pattern collection that you want to
retrieve. If you do not specify a name, the API returns information for all
collections.
[[ccr-get-auto-follow-pattern-examples]]
==== {api-examples-title}
This example retrieves information about an auto-follow pattern collection This example retrieves information about an auto-follow pattern collection
named `my_auto_follow_pattern`: named `my_auto_follow_pattern`:

71
docs/reference/ccr/apis/auto-follow/put-auto-follow-pattern.asciidoc
View File

@ -8,15 +8,8 @@
Creates an auto-follow pattern. Creates an auto-follow pattern.
==== Description [[ccr-put-auto-follow-pattern-request]]
==== {api-request-title}
This API creates a new named collection of
{stack-ov}/ccr-auto-follow.html[auto-follow patterns] against the remote cluster
specified in the request body. Newly created indices on the remote cluster
matching any of the specified patterns will be automatically configured as follower
indices.
==== Request
[source,js] [source,js]
-------------------------------------------------- --------------------------------------------------
@ -48,35 +41,49 @@ DELETE /_ccr/auto_follow/auto_follow_pattern_name
////////////////////////// //////////////////////////
==== Path Parameters [[ccr-put-auto-follow-pattern-prereqs]]
`auto_follow_pattern_name` (required):: ==== {api-prereq-title}
(string) name of the collection of auto-follow patterns
==== Request Body * If the {es} {security-features} are enabled, you must have `read` and `monitor`
`remote_cluster`::
(required string) the <<modules-remote-clusters,remote cluster>> containing the
leader indices to match against
`leader_index_patterns`::
(array) an array of simple index patterns to match against indices in the
remote cluster specified by the `remote_cluster` field
`follow_index_pattern`::
(string) the name of follower index; the template `{{leader_index}}` can be
used to derive the name of the follower index from the name of the leader
index
include::../follow-request-body.asciidoc[]
==== Authorization
If the {es} {security-features} are enabled, you must have `read` and `monitor`
index privileges for the leader index patterns. You must also have `manage_ccr` index privileges for the leader index patterns. You must also have `manage_ccr`
cluster privileges on the cluster that contains the follower index. For more cluster privileges on the cluster that contains the follower index. For more
information, see information, see
{stack-ov}/security-privileges.html[Security privileges]. {stack-ov}/security-privileges.html[Security privileges].
==== Example [[ccr-put-auto-follow-pattern-desc]]
==== {api-description-title}
This API creates a new named collection of
{stack-ov}/ccr-auto-follow.html[auto-follow patterns] against the remote cluster
specified in the request body. Newly created indices on the remote cluster
matching any of the specified patterns will be automatically configured as follower
indices.
[[ccr-put-auto-follow-pattern-path-parms]]
==== {api-path-parms-title}
`<auto_follow_pattern_name>` (Required)::
(string) The name of the collection of auto-follow patterns.
[[ccr-put-auto-follow-pattern-request-body]]
==== {api-request-body-title}
`remote_cluster` (Required)::
(string) The <<modules-remote-clusters,remote cluster>> containing the
leader indices to match against.
`leader_index_patterns` (Optional)::
(array) An array of simple index patterns to match against indices in the
remote cluster specified by the `remote_cluster` field.
`follow_index_pattern` (Optional)::
(string) The name of follower index. The template `{{leader_index}}` can be
used to derive the name of the follower index from the name of the leader
index.
include::../follow-request-body.asciidoc[]
[[ccr-put-auto-follow-pattern-examples]]
==== {api-examples-title}
This example creates an auto-follow pattern named `my_auto_follow_pattern`: This example creates an auto-follow pattern named `my_auto_follow_pattern`:

51
docs/reference/ccr/apis/follow-request-body.asciidoc
View File

@ -1,48 +1,49 @@
[testenv="platinum"] [testenv="platinum"]
`max_read_request_operation_count`:: `max_read_request_operation_count`::
(integer) the maximum number of operations to pull per read from the remote (integer) The maximum number of operations to pull per read from the remote
cluster cluster.
`max_outstanding_read_requests`:: `max_outstanding_read_requests`::
(long) the maximum number of outstanding reads requests from the remote (long) The maximum number of outstanding reads requests from the remote
cluster cluster.
`max_read_request_size`:: `max_read_request_size`::
(<<byte-units,byte value>>) the maximum size in bytes of per read of a batch (<<byte-units,byte value>>) The maximum size in bytes of per read of a batch
of operations pulled from the remote cluster of operations pulled from the remote cluster.
`max_write_request_operation_count`:: `max_write_request_operation_count`::
(integer) the maximum number of operations per bulk write request executed on (integer) The maximum number of operations per bulk write request executed on
the follower the follower.
`max_write_request_size`:: `max_write_request_size`::
(<<byte-units,byte value>>) the maximum total bytes of operations per bulk write request (<<byte-units,byte value>>) The maximum total bytes of operations per bulk write request
executed on the follower executed on the follower.
`max_outstanding_write_requests`:: `max_outstanding_write_requests`::
(integer) the maximum number of outstanding write requests on the follower (integer) The maximum number of outstanding write requests on the follower.
`max_write_buffer_count`:: `max_write_buffer_count`::
(integer) the maximum number of operations that can be queued for writing; (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 When this limit is reached, reads from the remote cluster will be deferred
until the number of queued operations goes below the limit until the number of queued operations goes below the limit.
`max_write_buffer_size`:: `max_write_buffer_size`::
(<<byte-units,byte value>>) the maximum total bytes of operations that can be queued for (<<byte-units,byte value>>) The maximum total bytes of operations that can be
writing; when this limit is reached, reads from the remote cluster will be queued for
deferred until the total bytes of queued operations goes below the limit 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`:: `max_retry_delay`::
(<<time-units,time value>>) the maximum time to wait before retrying an (<<time-units,time value>>) The maximum time to wait before retrying an
operation that failed exceptionally; an exponential backoff strategy is operation that failed exceptionally. An exponential backoff strategy is
employed when retrying employed when retrying.
`read_poll_timeout`:: `read_poll_timeout`::
(<<time-units,time value>>) the maximum time to wait for new operations on the (<<time-units,time value>>) The maximum time to wait for new operations on the
remote cluster when the follower index is synchronized with the leader index; 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 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 follower so that it can update some statistics. Then the follower will
immediately attempt to read from the leader again immediately attempt to read from the leader again.
===== Default values ===== Default values

75
docs/reference/ccr/apis/follow/get-follow-info.asciidoc
View File

@ -8,13 +8,8 @@
Retrieves information about all follower indices. Retrieves information about all follower indices.
==== Description [[ccr-get-follow-info-request]]
==== {api-request-title}
This API lists the parameters and the status for each follower index.
For example, the results include follower index names, leader index names,
replication options and whether the follower indices are active or paused.
==== Request
////////////////////////// //////////////////////////
@ -46,88 +41,100 @@ GET /<index>/_ccr/info
// CONSOLE // CONSOLE
// TEST[s/<index>/follower_index/] // TEST[s/<index>/follower_index/]
==== Path Parameters [[ccr-get-follow-info-prereqs]]
`index` :: ==== {api-prereq-title}
(string) A comma-delimited list of follower index patterns
==== Results * If the {es} {security-features} are enabled, you must have `monitor` cluster
privileges. For more information, see
{stack-ov}/security-privileges.html[Security privileges].
[[ccr-get-follow-info-desc]]
==== {api-description-title}
This API lists the parameters and the status for each follower index.
For example, the results include follower index names, leader index names,
replication options and whether the follower indices are active or paused.
[[ccr-get-follow-info-path-parms]]
==== {api-path-parms-title}
`<index>` (Required)::
(string) A comma-delimited list of follower index patterns.
[[ccr-get-follow-info-response-body]]
==== {api-response-body-title}
This API returns the following information: This API returns the following information:
`follower_indices`:: `follower_indices`::
(array) An array of follower index statistics (array) An array of follower index statistics.
The `indices` array consists of objects containing several fields: The `indices` array consists of objects containing several fields:
`indices[].follower_index`:: `indices[].follower_index`::
(string) The name of the follower index (string) The name of the follower index.
`indices[].remote_cluster`:: `indices[].remote_cluster`::
(string) The <<modules-remote-clusters,remote cluster>> that contains the (string) The <<modules-remote-clusters,remote cluster>> that contains the
leader index leader index.
`indices[].leader_index`:: `indices[].leader_index`::
(string) The name of the index in the leader cluster that is followed (string) The name of the index in the leader cluster that is followed.
`indices[].status`:: `indices[].status`::
(string) Whether index following is `active` or `paused` (string) Whether index following is `active` or `paused`.
`indices[].parameters`:: `indices[].parameters`::
(object) An object that encapsulates {ccr} parameters (object) An object that encapsulates {ccr} parameters.
The `parameters` contains the following fields: The `parameters` contains the following fields:
`indices[].parameters.max_read_request_operation_count`:: `indices[].parameters.max_read_request_operation_count`::
(integer) The maximum number of operations to pull per read from the remote (integer) The maximum number of operations to pull per read from the remote
cluster cluster.
`indices[].parameters.max_outstanding_read_requests`:: `indices[].parameters.max_outstanding_read_requests`::
(long) The maximum number of outstanding read requests from the remote cluster (long) The maximum number of outstanding read requests from the remote cluster.
`indices[].parameters.max_read_request_size`:: `indices[].parameters.max_read_request_size`::
(<<byte-units,byte value>>) The maximum size in bytes of per read of a batch (<<byte-units,byte value>>) The maximum size in bytes of per read of a batch
of operations pulled from the remote cluster of operations pulled from the remote cluster.
`indices[].parameters.max_write_request_operation_count`:: `indices[].parameters.max_write_request_operation_count`::
(integer) The maximum number of operations per bulk write request executed on (integer) The maximum number of operations per bulk write request executed on
the follower the follower.
`indices[].parameters.max_write_request_size`:: `indices[].parameters.max_write_request_size`::
(<<byte-units,byte value>>) The maximum total bytes of operations per bulk (<<byte-units,byte value>>) The maximum total bytes of operations per bulk
write request executed on the follower write request executed on the follower.
`indices[].parameters.max_outstanding_write_requests`:: `indices[].parameters.max_outstanding_write_requests`::
(integer) The maximum number of outstanding write requests on the follower (integer) The maximum number of outstanding write requests on the follower.
`indices[].parameters.max_write_buffer_count`:: `indices[].parameters.max_write_buffer_count`::
(integer) The maximum number of operations that can be queued for writing. (integer) The maximum number of operations that can be queued for writing.
When this limit is reached, reads from the remote cluster are deferred until When this limit is reached, reads from the remote cluster are deferred until
the number of queued operations goes below the limit the number of queued operations goes below the limit.
`indices[].parameters.max_write_buffer_size`:: `indices[].parameters.max_write_buffer_size`::
(<<byte-units,byte value>>) The maximum total bytes of operations that can be (<<byte-units,byte value>>) The maximum total bytes of operations that can be
queued for writing. When this limit is reached, reads from the remote cluster queued for writing. When this limit is reached, reads from the remote cluster
are deferred until the total bytes of queued operations goes below the limit are deferred until the total bytes of queued operations goes below the limit.
`indices[].parameters.max_retry_delay`:: `indices[].parameters.max_retry_delay`::
(<<time-units,time value>>) The maximum time to wait before retrying an (<<time-units,time value>>) The maximum time to wait before retrying an
operation that failed exceptionally. An exponential backoff strategy is operation that failed exceptionally. An exponential backoff strategy is
employed when retrying employed when retrying.
`indices[].parameters.read_poll_timeout`:: `indices[].parameters.read_poll_timeout`::
(<<time-units,time value>>) The maximum time to wait for new operations on the (<<time-units,time value>>) The maximum time to wait for new operations on the
remote cluster when the follower index is synchronized with the leader index. remote cluster when the follower index is synchronized with the leader index.
When the timeout has elapsed, the poll for operations returns to the follower When the timeout has elapsed, the poll for operations returns to the follower
so that it can update some statistics, then the follower immediately attempts so that it can update some statistics, then the follower immediately attempts
to read from the leader again to read from the leader again.
==== Authorization [[ccr-get-follow-info-examples]]
==== {api-examples-title}
If the {es} {security-features} are enabled, you must have `monitor` cluster
privileges. For more information, see
{stack-ov}/security-privileges.html[Security privileges].
==== Example
This example retrieves follower info: This example retrieves follower info:

141
docs/reference/ccr/apis/follow/get-follow-stats.asciidoc
View File

@ -8,12 +8,8 @@
Get follower stats. Get follower stats.
==== Description [[ccr-get-follow-stats-request]]
==== {api-request-title}
This API gets follower stats. This API will return shard-level stats about the
following tasks associated with each shard for the specified indices.
==== Request
////////////////////////// //////////////////////////
@ -45,148 +41,167 @@ GET /<index>/_ccr/stats
// CONSOLE // CONSOLE
// TEST[s/<index>/follower_index/] // TEST[s/<index>/follower_index/]
==== Path Parameters [[ccr-get-follow-stats-prereqs]]
`index` :: ==== {api-prereq-title}
(string) a comma-delimited list of index patterns
==== Results * If the {es} {security-features} are enabled, you must have `monitor` cluster
privileges on the cluster that contains the follower index. For more information,
see {stack-ov}/security-privileges.html[Security privileges].
[[ccr-get-follow-stats-desc]]
==== {api-description-title}
This API gets follower stats. This API will return shard-level stats about the
following tasks associated with each shard for the specified indices.
[[ccr-get-follow-stats-path-parms]]
==== {api-path-parms-title}
`<index>` (Required)::
(string) A comma-delimited list of index patterns.
[[ccr-get-follow-stats-response-body]]
==== {api-response-body-title}
This API returns the following information: This API returns the following information:
`indices`:: `indices`::
(array) an array of follower index statistics (array) An array of follower index statistics.
The `indices` array consists of objects containing two fields: The `indices` array consists of objects containing two fields:
`indices[].index`:: `indices[].index`::
(string) the name of the follower index (string) The name of the follower index.
`indices[].shards`:: `indices[].shards`::
(array) an array of shard-level following task statistics (array) An array of shard-level following task statistics.
The `shards` array consists of objects containing the following fields: The `shards` array consists of objects containing the following fields:
`indices[].shards[].remote_cluster`:: `indices[].shards[].remote_cluster`::
(string) the <modules-remote-clusters,remote cluster>> containing the leader (string) The <modules-remote-clusters,remote cluster>> containing the leader
index index.
`indices[].shards[].leader_index`:: `indices[].shards[].leader_index`::
(string) the name of the index in the leader cluster being followed (string) The name of the index in the leader cluster being followed.
`indices[].shards[].follower_index`:: `indices[].shards[].follower_index`::
(string) the name of the follower index (string) The name of the follower index.
`indices[].shards[].shard_id`:: `indices[].shards[].shard_id`::
(integer) the numerical shard ID, with values from 0 to one less than the (integer) The numerical shard ID, with values from 0 to one less than the
number of replicas number of replicas.
`indices[].shards[].leader_global_checkpoint`:: `indices[].shards[].leader_global_checkpoint`::
(long) the current global checkpoint on the leader known to the follower task (long) The current global checkpoint on the leader known to the follower task.
`indices[].shards[].leader_max_seq_no`:: `indices[].shards[].leader_max_seq_no`::
(long) the current maximum sequence number on the leader known to the follower (long) The current maximum sequence number on the leader known to the follower
task task.
`indices[].shards[].follower_global_checkpoint`:: `indices[].shards[].follower_global_checkpoint`::
(long) the current global checkpoint on the follower; the difference between the (long) The current global checkpoint on the follower. The difference between the
`leader_global_checkpoint` and the `follower_global_checkpoint` is an `leader_global_checkpoint` and the `follower_global_checkpoint` is an
indication of how much the follower is lagging the leader indication of how much the follower is lagging the leader.
`indices[].shards[].follower_max_seq_no`:: `indices[].shards[].follower_max_seq_no`::
(long) the current maximum sequence number on the follower (long) The current maximum sequence number on the follower.
`indices[].shards[].last_requested_seq_no`:: `indices[].shards[].last_requested_seq_no`::
(long) the starting sequence number of the last batch of operations requested (long) The starting sequence number of the last batch of operations requested
from the leader from the leader.
`indices[].shards[].outstanding_read_requests`:: `indices[].shards[].outstanding_read_requests`::
(integer) the number of active read requests from the follower (integer) The number of active read requests from the follower.
`indices[].shards[].outstanding_write_requests`:: `indices[].shards[].outstanding_write_requests`::
(integer) the number of active bulk write requests on the follower (integer) The number of active bulk write requests on the follower.
`indices[].shards[].write_buffer_operation_count`:: `indices[].shards[].write_buffer_operation_count`::
(integer) the number of write operations queued on the follower (integer) The number of write operations queued on the follower.
`indices[].shards[].follower_mapping_version`:: `indices[].shards[].follower_mapping_version`::
(long) the mapping version the follower is synced up to (long) The mapping version the follower is synced up to.
`indices[].shards[].follower_settings_version`:: `indices[].shards[].follower_settings_version`::
(long) the index settings version the follower is synced up to (long) The index settings version the follower is synced up to.
`indices[].shards[].follower_aliases_version`:: `indices[].shards[].follower_aliases_version`::
(long) the index aliases version the follower is synced up to (long) The index aliases version the follower is synced up to.
`indices[].shards[].total_read_time_millis`:: `indices[].shards[].total_read_time_millis`::
(long) the total time reads were outstanding, measured from the time a read (long) The total time reads were outstanding, measured from the time a read
was sent to the leader to the time a reply was returned to the follower was sent to the leader to the time a reply was returned to the follower.
`indices[].shards[].total_read_remote_exec_time_millis`:: `indices[].shards[].total_read_remote_exec_time_millis`::
(long) the total time reads spent executing on the remote cluster (long) The total time reads spent executing on the remote cluster.
`indices[].shards[].successful_read_requests`:: `indices[].shards[].successful_read_requests`::
(long) the number of successful fetches (long) The number of successful fetches.
`indices[].shards[].failed_read_requests`:: `indices[].shards[].failed_read_requests`::
(long) the number of failed reads (long) The number of failed reads.
`indices[].shards[].operations_read`:: `indices[].shards[].operations_read`::
(long) the total number of operations read from the leader (long) The total number of operations read from the leader.
`indices[].shards[].bytes_read`:: `indices[].shards[].bytes_read`::
(long) the total of transferred bytes read from the leader (note this is only (long) The total of transferred bytes read from the leader.
an estimate, and does not account for compression if enabled) +
--
NOTE: This is only an estimate and does not account for compression if enabled.
--
`indices[].shards[].total_write_time_millis`:: `indices[].shards[].total_write_time_millis`::
(long) the total time spent writing on the follower (long) The total time spent writing on the follower.
`indices[].shards[].write_buffer_size_in_bytes`:: `indices[].shards[].write_buffer_size_in_bytes`::
(long) the total number of bytes of operations currently queued for writing (long) The total number of bytes of operations currently queued for writing.
`indices[].shards[].successful_write_requests`:: `indices[].shards[].successful_write_requests`::
(long) the number of bulk write requests executed on the follower (long) The number of bulk write requests executed on the follower.
`indices[].shards[].failed_write_requests`:: `indices[].shards[].failed_write_requests`::
(long) the number of failed bulk write requests executed on the follower (long) The number of failed bulk write requests executed on the follower.
`indices[].shards[].operations_written`:: `indices[].shards[].operations_written`::
(long) the number of operations written on the follower (long) The number of operations written on the follower.
`indices[].shards[].read_exceptions`:: `indices[].shards[].read_exceptions`::
(array) an array of objects representing failed reads (array) An array of objects representing failed reads.
The `read_exceptions` array consists of objects containing the following The `read_exceptions` array consists of objects containing the following
fields: fields:
`indices[].shards[].read_exceptions[].from_seq_no`:: `indices[].shards[].read_exceptions[].from_seq_no`::
(long) the starting sequence number of the batch requested from the leader (long) The starting sequence number of the batch requested from the leader.
`indices[].shards[].read_exceptions[].retries`:: `indices[].shards[].read_exceptions[].retries`::
(integer) the number of times the batch has been retried (integer) The number of times the batch has been retried.
`indices[].shards[].read_exceptions[].exception`:: `indices[].shards[].read_exceptions[].exception`::
(object) represents the exception that caused the read to fail (object) Represents the exception that caused the read to fail.
Continuing with the fields from `shards`: Continuing with the fields from `shards`:
`indices[].shards[].time_since_last_read_millis`:: `indices[].shards[].time_since_last_read_millis`::
(long) the number of milliseconds since a read request was sent to the leader; (long) The number of milliseconds since a read request was sent to the leader.
note that when the follower is caught up to the leader, this number will +
--
NOTE: When the follower is caught up to the leader, this number will
increase up to the configured `read_poll_timeout` at which point another read increase up to the configured `read_poll_timeout` at which point another read
request will be sent to the leader request will be sent to the leader.
--
`indices[].fatal_exception`:: `indices[].fatal_exception`::
(object) an object representing a fatal exception that cancelled the following (object) An object representing a fatal exception that cancelled the following
task; in this situation, the following task must be resumed manually with the task. In this situation, the following task must be resumed manually with the
<<ccr-post-resume-follow,resume follower API>> <<ccr-post-resume-follow,resume follower API>>.
==== Authorization [[ccr-get-follow-stats-examples]]
==== {api-examples-title}
If the {es} {security-features} are enabled, you must have `monitor` cluster
privileges on the cluster that contains the follower index. For more information,
see {stack-ov}/security-privileges.html[Security privileges].
==== Example
This example retrieves follower stats: This example retrieves follower stats:

103
docs/reference/ccr/apis/follow/post-forget-follower.asciidoc
View File

@ -1,36 +1,15 @@
[role="xpack"] [role="xpack"]
[testenv="platinum"] [testenv="platinum"]
[[ccr-post-forget-follower]] [[ccr-post-forget-follower]]
=== Forget Follower API === Forget follower API
++++ ++++
<titleabbrev>Forget Follower</titleabbrev> <titleabbrev>Forget follower</titleabbrev>
++++ ++++
Removes the follower retention leases from the leader. Removes the follower retention leases from the leader.
==== Description [[ccr-post-forget-follower-request]]
==== {api-request-title}
A following index takes out retention leases on its leader index. These
retention leases are used to increase the likelihood that the shards of the
leader index retain the history of operations that the shards of the following
index need to execute replication. When a follower index is converted to a
regular index via the <<ccr-post-unfollow,unfollow API>> (either via explicit
execution of this API, or implicitly via {ilm}), these retention leases are
removed. However, removing these retention leases can fail (e.g., if the remote
cluster containing the leader index is unavailable). While these retention
leases will eventually expire on their own, their extended existence can cause
the leader index to hold more history than necessary, and prevent {ilm} from
performing some operations on the leader index. This API exists to enable
manually removing these retention leases when the unfollow API was unable to do
so.
NOTE: This API does not stop replication by a following index. If you use this
API targeting a follower index that is still actively following, the following
index will add back retention leases on the leader. The only purpose of this API
is to handle the case of failure to remove the following retention leases after
the <<ccr-post-unfollow,unfollow API>> is invoked.
==== Request
////////////////////////// //////////////////////////
@ -89,33 +68,61 @@ POST /<leader_index>/_ccr/forget_follower
// TESTRESPONSE[s/"failed" : 0/"failed" : $body._shards.failed/] // TESTRESPONSE[s/"failed" : 0/"failed" : $body._shards.failed/]
// TESTRESPONSE[s/"failures" : \[ \]/"failures" : $body._shards.failures/] // TESTRESPONSE[s/"failures" : \[ \]/"failures" : $body._shards.failures/]
==== Path Parameters [[ccr-post-forget-follower-prereqs]]
==== {api-prereq-title}
`leader_index` (required):: * If the {es} {security-features} are enabled, you must have `manage_leader_index`
(string) the name of the leader index
==== Request Body
`follower_cluster` (required)::
(string) the name of the cluster containing the follower index
`follower_index` (required)::
(string) the name of the follower index
`follower_index_uuid` (required)::
(string) the UUID of the follower index
`leader_remote_cluster` (required)::
(string) the alias (from the perspective of the cluster containing the
follower index) of the <<modules-remote-clusters,remote cluster>> containing
the leader index
==== Authorization
If the {es} {security-features} are enabled, you must have `manage_leader_index`
index privileges for the leader index. For more information, see index privileges for the leader index. For more information, see
{stack-ov}/security-privileges.html[Security privileges]. {stack-ov}/security-privileges.html[Security privileges].
==== Example [[ccr-post-forget-follower-desc]]
==== {api-description-title}
A following index takes out retention leases on its leader index. These
retention leases are used to increase the likelihood that the shards of the
leader index retain the history of operations that the shards of the following
index need to execute replication. When a follower index is converted to a
regular index via the <<ccr-post-unfollow,unfollow API>> (either via explicit
execution of this API, or implicitly via {ilm}), these retention leases are
removed. However, removing these retention leases can fail (e.g., if the remote
cluster containing the leader index is unavailable). While these retention
leases will eventually expire on their own, their extended existence can cause
the leader index to hold more history than necessary, and prevent {ilm} from
performing some operations on the leader index. This API exists to enable
manually removing these retention leases when the unfollow API was unable to do
so.
NOTE: This API does not stop replication by a following index. If you use this
API targeting a follower index that is still actively following, the following
index will add back retention leases on the leader. The only purpose of this API
is to handle the case of failure to remove the following retention leases after
the <<ccr-post-unfollow,unfollow API>> is invoked.
[[ccr-post-forget-follower-path-parms]]
==== {api-path-parms-title}
`<leader_index>` (Required)::
(string) the name of the leader index
[[ccr-post-forget-follower-request-body]]
==== {api-request-body-title}
`follower_cluster` (Required)::
(string) The name of the cluster containing the follower index.
`follower_index` (Required)::
(string) The name of the follower index.
`follower_index_uuid` (Required)::
(string) The UUID of the follower index.
`leader_remote_cluster` (Required)::
(string) The alias (from the perspective of the cluster containing the
follower index) of the <<modules-remote-clusters,remote cluster>> containing
the leader index.
[[ccr-post-forget-follower-examples]]
==== {api-examples-title}
This example removes the follower retention leases for `follower_index` from This example removes the follower retention leases for `follower_index` from
`leader_index`. `leader_index`.

39
docs/reference/ccr/apis/follow/post-pause-follow.asciidoc
View File

@ -8,15 +8,8 @@
Pauses a follower index. Pauses a follower index.
==== Description [[ccr-post-pause-follow-request]]
==== {api-request-title}
This API pauses a follower index. When this API returns, the follower index will
not fetch any additional operations from the leader index. You can resume
following with the <<ccr-post-resume-follow,resume follower API>>. Pausing and
resuming a follower index can be used to change the configuration of the
following task.
==== Request
////////////////////////// //////////////////////////
@ -41,20 +34,30 @@ POST /<follower_index>/_ccr/pause_follow
// CONSOLE // CONSOLE
// TEST[s/<follower_index>/follower_index/] // TEST[s/<follower_index>/follower_index/]
==== Path Parameters [[ccr-post-pause-follow-prereqs]]
==== {api-prereq-title}
`follower_index` (required):: * If the {es} {security-features} are enabled, you must have `manage_ccr` cluster
(string) the name of the follower index
==== Authorization
If the {es} {security-features} are enabled, you must have `manage_ccr` cluster
privileges on the cluster that contains the follower index. For more information, privileges on the cluster that contains the follower index. For more information,
see {stack-ov}/security-privileges.html[Security privileges]. see {stack-ov}/security-privileges.html[Security privileges].
[[ccr-post-pause-follow-desc]]
==== {api-description-title}
==== Example This API pauses a follower index. When this API returns, the follower index will
not fetch any additional operations from the leader index. You can resume
following with the <<ccr-post-resume-follow,resume follower API>>. Pausing and
resuming a follower index can be used to change the configuration of the
following task.
[[ccr-post-pause-follow-path-parms]]
==== {api-path-parms-title}
`<follower_index>` (Required)::
(string) The name of the follower index.
[[ccr-post-pause-follow-examples]]
==== {api-examples-title}
This example pauses a follower index named `follower_index`: This example pauses a follower index named `follower_index`:

44
docs/reference/ccr/apis/follow/post-resume-follow.asciidoc
View File

@ -8,14 +8,8 @@
Resumes a follower index. Resumes a follower index.
==== Description [[ccr-post-resume-follow-request]]
==== {api-request-title}
This API resumes a follower index that has been paused either explicitly with
the <<ccr-post-pause-follow, pause follower API>> or implicitly due to
execution that can not be retried due to failure during following. When this API
returns, the follower index will resume fetching operations from the leader index.
==== Request
////////////////////////// //////////////////////////
@ -53,23 +47,35 @@ POST /<follower_index>/_ccr/resume_follow
// TEST[s/<remote_cluster>/remote_cluster/] // TEST[s/<remote_cluster>/remote_cluster/]
// TEST[s/<leader_index>/leader_index/] // TEST[s/<leader_index>/leader_index/]
==== Path Parameters [[ccr-post-resume-follow-prereqs]]
==== {api-prereq-title}
`follower_index` (required):: * If the {es} {security-features} are enabled, you must have `write` and `monitor`
(string) the name of the follower index
==== Request Body
include::../follow-request-body.asciidoc[]
==== Authorization
If the {es} {security-features} are enabled, you must have `write` and `monitor`
index privileges for the follower index. You must have `read` and `monitor` 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 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, privileges on the cluster that contains the follower index. For more information,
see {stack-ov}/security-privileges.html[Security privileges]. see {stack-ov}/security-privileges.html[Security privileges].
==== Example [[ccr-post-resume-follow-desc]]
==== {api-description-title}
This API resumes a follower index that has been paused either explicitly with
the <<ccr-post-pause-follow, pause follower API>> or implicitly due to
execution that can not be retried due to failure during following. When this API
returns, the follower index will resume fetching operations from the leader index.
[[ccr-post-resume-follow-path-parms]]
==== {api-path-parms-title}
`<follower_index>` (Required)::
(string) The name of the follower index.
[[ccr-post-resume-follow-request-body]]
==== {api-request-body-title}
include::../follow-request-body.asciidoc[]
[[ccr-post-resume-follow-examples]]
==== {api-examples-title}
This example resumes a follower index named `follower_index`: This example resumes a follower index named `follower_index`:

45
docs/reference/ccr/apis/follow/post-unfollow.asciidoc
View File

@ -8,18 +8,8 @@
Converts a follower index to a regular index. Converts a follower index to a regular index.
==== Description [[ccr-post-unfollow-request]]
==== {api-request-title}
This API stops the following task associated with a follower index and removes
index metadata and settings associated with {ccr}. This enables the index to
treated as a regular index. The follower index must be paused and closed before
invoking the unfollow API.
NOTE: Currently {ccr} does not support converting an existing regular index to a
follower index. Converting a follower index to a regular index is an
irreversible operation.
==== Request
////////////////////////// //////////////////////////
@ -48,18 +38,33 @@ POST /<follower_index>/_ccr/unfollow
// CONSOLE // CONSOLE
// TEST[s/<follower_index>/follower_index/] // TEST[s/<follower_index>/follower_index/]
==== Path Parameters [[ccr-post-unfollow-prereqs]]
==== {api-prereq-title}
`follower_index` (required):: * If the {es} {security-features} are enabled, you must have `manage_follow_index`
(string) the name of the follower index
==== Authorization
If the {es} {security-features} are enabled, you must have `manage_follow_index`
index privileges for the follower index. For more information, see index privileges for the follower index. For more information, see
{stack-ov}/security-privileges.html[Security privileges]. {stack-ov}/security-privileges.html[Security privileges].
==== Example [[ccr-post-unfollow-desc]]
==== {api-description-title}
This API stops the following task associated with a follower index and removes
index metadata and settings associated with {ccr}. This enables the index to
treated as a regular index. The follower index must be paused and closed before
invoking the unfollow API.
NOTE: Currently {ccr} does not support converting an existing regular index to a
follower index. Converting a follower index to a regular index is an
irreversible operation.
[[ccr-post-unfollow-path-parms]]
==== {api-path-parms-title}
`<follower_index>` (Required)::
(string) The name of the follower index.
[[ccr-post-unfollow-examples]]
==== {api-examples-title}
This example converts `follower_index` from a follower index to a regular index: This example converts `follower_index` from a follower index to a regular index:

73
docs/reference/ccr/apis/follow/put-follow.asciidoc
View File

@ -8,13 +8,8 @@
Creates a follower index. Creates a follower index.
==== Description [[ccr-put-follow-request]]
==== {api-request-title}
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
{ccr} starts replicating operations from the leader index to the follower index.
==== Request
////////////////////////// //////////////////////////
@ -41,36 +36,54 @@ PUT /<follower_index>/_ccr/follow?wait_for_active_shards=1
// TEST[s/<remote_cluster>/remote_cluster/] // TEST[s/<remote_cluster>/remote_cluster/]
// TEST[s/<leader_index>/leader_index/] // TEST[s/<leader_index>/leader_index/]
The `wait_for_active_shards` parameter specifies the number of shards to wait on being active [[ccr-put-follow-prereqs]]
before responding. This defaults to waiting on none of the shards to be active. A shard must ==== {api-prereq-title}
be restored from the leader index being active. Restoring a follower shard requires transferring
all the remote Lucene segment files to the follower index.
==== Path Parameters * If the {es} {security-features} are enabled, you must have `write`, `monitor`,
`follower_index` (required)::
(string) the name of the follower index
==== Request Body
`remote_cluster` (required)::
(string) the <<modules-remote-clusters,remote cluster>> containing the leader
index
`leader_index` (required)::
(string) the name of the index in the leader cluster to follow
include::../follow-request-body.asciidoc[]
==== Authorization
If the {es} {security-features} are enabled, you must have `write`, `monitor`,
and `manage_follow_index` index privileges for the follower index. You must have 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 `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. `manage_ccr` cluster privileges on the cluster that contains the follower index.
For more information, see For more information, see
{stack-ov}/security-privileges.html[Security privileges]. {stack-ov}/security-privileges.html[Security privileges].
==== Example [[ccr-put-follow-desc]]
==== {api-description-title}
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
{ccr} starts replicating operations from the leader index to the follower index.
[[ccr-put-follow-path-parms]]
==== {api-path-parms-title}
`<follower_index>` (Required)::
(string) The name of the follower index.
[[ccr-put-follow-query-params]]
==== {api-query-parms-title}
`wait_for_active_shards` (Optional)::
(integer) Specifies the number of shards to wait on being active before
responding. This defaults to waiting on none of the shards to be active. A
shard must be restored from the leader index being active. Restoring a
follower shard requires transferring all the remote Lucene segment files to
the follower index.
[[ccr-put-follow-request-body]]
==== {api-request-body-title}
`remote_cluster` (Required)::
(string) The <<modules-remote-clusters,remote cluster>> containing the leader
index.
`leader_index` (Required)::
(string) The name of the index in the leader cluster to follow.
include::../follow-request-body.asciidoc[]
[[ccr-put-follow-examples]]
==== {api-examples-title}
This example creates a follower index named `follower_index`: This example creates a follower index named `follower_index`:

63
docs/reference/ccr/apis/get-ccr-stats.asciidoc
View File

@ -2,19 +2,15 @@
[testenv="platinum"] [testenv="platinum"]
[[ccr-get-stats]] [[ccr-get-stats]]
=== Get {ccr} stats API === Get {ccr} stats API
[subs="attributes"]
++++ ++++
<titleabbrev>Get CCR stats</titleabbrev> <titleabbrev>Get {ccr-init} stats</titleabbrev>
++++ ++++
Get {ccr} stats. Get {ccr} stats.
==== Description [[ccr-get-stats-request]]
==== {api-request-title}
This API gets {ccr} stats. This API will return all stats related to {ccr}. In
particular, this API returns stats about auto-following, and returns the same
shard-level stats as in the <<ccr-get-follow-stats,get follower stats API>>.
==== Request
////////////////////////// //////////////////////////
@ -45,46 +41,55 @@ GET /_ccr/stats
-------------------------------------------------- --------------------------------------------------
// CONSOLE // CONSOLE
==== Results ==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have `monitor` cluster
privileges on the cluster that contains the follower index. For more information,
see {stack-ov}/security-privileges.html[Security privileges].
[[ccr-get-stats-desc]]
==== {api-description-title}
This API gets {ccr} stats. This API will return all stats related to {ccr}. In
particular, this API returns stats about auto-following, and returns the same
shard-level stats as in the <<ccr-get-follow-stats,get follower stats API>>.
[[ccr-get-stats-response-body]]
==== {api-response-body-title}
This API returns the following information: This API returns the following information:
`auto_follow_stats`:: `auto_follow_stats`::
(object) an object representing stats for the auto-follow coordinator (object) An object representing stats for the auto-follow coordinator.
This object consists of the following fields: This object consists of the following fields:
`auto_follow_stats.number_of_failed_follow_indices`:: `auto_follow_stats.number_of_failed_follow_indices`::
(long) the number of indices that the auto-follow coordinator failed to (long) The number of indices that the auto-follow coordinator failed to
automatically follow; the causes of recent failures are captured in the logs automatically follow. The causes of recent failures are captured in the logs
of the elected master node, and in the of the elected master node and in the
`auto_follow_stats.recent_auto_follow_errors` field `auto_follow_stats.recent_auto_follow_errors` field.
`auto_follow_stats.number_of_failed_remote_cluster_state_requests`:: `auto_follow_stats.number_of_failed_remote_cluster_state_requests`::
(long) the number of times that the auto-follow coordinator failed to retrieve (long) The number of times that the auto-follow coordinator failed to retrieve
the cluster state from a remote cluster registered in a collection of the cluster state from a remote cluster registered in a collection of
auto-follow patterns auto-follow patterns.
`auto_follow_stats.number_of_successful_follow_indices`:: `auto_follow_stats.number_of_successful_follow_indices`::
(long) the number of indices that the auto-follow coordinator successfully (long) The number of indices that the auto-follow coordinator successfully
followed followed.
`auto_follow_stats.recent_auto_follow_errors`:: `auto_follow_stats.recent_auto_follow_errors`::
(array) an array of objects representing failures by the auto-follow (array) An array of objects representing failures by the auto-follow
coordinator coordinator.
`follow_stats`:: `follow_stats`::
(object) an object representing shard-level stats for follower indices; refer (object) An object representing shard-level stats for follower indices; refer
to the details of the response in the to the details of the response in the
<<ccr-get-follow-stats,get follower stats API>> <<ccr-get-follow-stats,get follower stats API>>.
==== Authorization [[ccr-get-stats-examples]]
==== {api-examples-title}
If the {es} {security-features} are enabled, you must have `monitor` cluster
privileges on the cluster that contains the follower index. For more information,
see {stack-ov}/security-privileges.html[Security privileges].
==== Example
This example retrieves {ccr} stats: This example retrieves {ccr} stats: