diff --git a/docs/reference/ccr/apis/auto-follow/delete-auto-follow-pattern.asciidoc b/docs/reference/ccr/apis/auto-follow/delete-auto-follow-pattern.asciidoc index e2e91334402..84132d5a95a 100644 --- a/docs/reference/ccr/apis/auto-follow/delete-auto-follow-pattern.asciidoc +++ b/docs/reference/ccr/apis/auto-follow/delete-auto-follow-pattern.asciidoc @@ -8,12 +8,8 @@ Delete auto-follow patterns. -==== Description - -This API deletes a configured collection of -{stack-ov}/ccr-auto-follow.html[auto-follow patterns]. - -==== Request +[[ccr-delete-auto-follow-pattern-request]] +==== {api-request-title} ////////////////////////// @@ -42,17 +38,28 @@ DELETE /_ccr/auto_follow/ // CONSOLE // TEST[s//my_auto_follow_pattern/] -==== Path Parameters -`auto_follow_pattern_name` (required):: - (string) specifies the auto-follow pattern collection to delete +[[ccr-delete-auto-follow-pattern-prereqs]] +==== {api-prereq-title} -==== 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, 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} + +`` (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 `my_auto_follow_pattern`: diff --git a/docs/reference/ccr/apis/auto-follow/get-auto-follow-pattern.asciidoc b/docs/reference/ccr/apis/auto-follow/get-auto-follow-pattern.asciidoc index 9eb18b0aa00..25122ab5f3a 100644 --- a/docs/reference/ccr/apis/auto-follow/get-auto-follow-pattern.asciidoc +++ b/docs/reference/ccr/apis/auto-follow/get-auto-follow-pattern.asciidoc @@ -8,12 +8,8 @@ Get auto-follow patterns. -==== Description - -This API gets configured {stack-ov}/ccr-auto-follow.html[auto-follow patterns]. -This API will return the specified auto-follow pattern collection. - -==== Request +[[ccr-get-auto-follow-pattern-request]] +==== {api-request-title} ////////////////////////// @@ -56,19 +52,29 @@ GET /_ccr/auto_follow/ // CONSOLE // TEST[s//my_auto_follow_pattern/] -==== Path Parameters -`auto_follow_pattern_name`:: - (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-prereqs]] +==== {api-prereq-title} -==== 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, 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} + +`` (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 named `my_auto_follow_pattern`: diff --git a/docs/reference/ccr/apis/auto-follow/put-auto-follow-pattern.asciidoc b/docs/reference/ccr/apis/auto-follow/put-auto-follow-pattern.asciidoc index 3ed6cd94702..6df2f2c2f82 100644 --- a/docs/reference/ccr/apis/auto-follow/put-auto-follow-pattern.asciidoc +++ b/docs/reference/ccr/apis/auto-follow/put-auto-follow-pattern.asciidoc @@ -8,15 +8,8 @@ Creates an auto-follow pattern. -==== Description - -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 +[[ccr-put-auto-follow-pattern-request]] +==== {api-request-title} [source,js] -------------------------------------------------- @@ -48,35 +41,49 @@ DELETE /_ccr/auto_follow/auto_follow_pattern_name ////////////////////////// -==== Path Parameters -`auto_follow_pattern_name` (required):: - (string) name of the collection of auto-follow patterns +[[ccr-put-auto-follow-pattern-prereqs]] +==== {api-prereq-title} -==== Request Body -`remote_cluster`:: - (required string) the <> 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` +* 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` cluster privileges on the cluster that contains the follower index. For more information, see {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} +`` (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 <> 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`: diff --git a/docs/reference/ccr/apis/follow-request-body.asciidoc b/docs/reference/ccr/apis/follow-request-body.asciidoc index d8fb725f02b..e9c8892998f 100644 --- a/docs/reference/ccr/apis/follow-request-body.asciidoc +++ b/docs/reference/ccr/apis/follow-request-body.asciidoc @@ -1,48 +1,49 @@ [testenv="platinum"] `max_read_request_operation_count`:: - (integer) the maximum number of operations to pull per read from the remote - cluster + (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 + (long) The maximum number of outstanding reads requests from the remote + cluster. `max_read_request_size`:: - (<>) the maximum size in bytes of per read of a batch - of operations pulled from the remote cluster + (<>) 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 + (integer) The maximum number of operations per bulk write request executed on + the follower. `max_write_request_size`:: - (<>) the maximum total bytes of operations per bulk write request - executed on the follower + (<>) 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 + (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 + (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`:: - (<>) 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 + (<>) 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`:: - (<>) the maximum time to wait before retrying an - operation that failed exceptionally; an exponential backoff strategy is - employed when retrying + (<>) The maximum time to wait before retrying an + operation that failed exceptionally. An exponential backoff strategy is + employed when retrying. `read_poll_timeout`:: - (<>) 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 + (<>) 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. Then the follower will + immediately attempt to read from the leader again. ===== Default values diff --git a/docs/reference/ccr/apis/follow/get-follow-info.asciidoc b/docs/reference/ccr/apis/follow/get-follow-info.asciidoc index eca2f5e8e98..b226f60ec85 100644 --- a/docs/reference/ccr/apis/follow/get-follow-info.asciidoc +++ b/docs/reference/ccr/apis/follow/get-follow-info.asciidoc @@ -8,13 +8,8 @@ Retrieves information about all follower indices. -==== Description - -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 +[[ccr-get-follow-info-request]] +==== {api-request-title} ////////////////////////// @@ -46,88 +41,100 @@ GET //_ccr/info // CONSOLE // TEST[s//follower_index/] -==== Path Parameters -`index` :: - (string) A comma-delimited list of follower index patterns +[[ccr-get-follow-info-prereqs]] +==== {api-prereq-title} -==== 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} + +`` (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: `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: `indices[].follower_index`:: - (string) The name of the follower index + (string) The name of the follower index. `indices[].remote_cluster`:: (string) The <> that contains the - leader index + 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`:: - (string) Whether index following is `active` or `paused` + (string) Whether index following is `active` or `paused`. `indices[].parameters`:: - (object) An object that encapsulates {ccr} parameters + (object) An object that encapsulates {ccr} parameters. The `parameters` contains the following fields: `indices[].parameters.max_read_request_operation_count`:: (integer) The maximum number of operations to pull per read from the remote - cluster + cluster. `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`:: (<>) 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`:: (integer) The maximum number of operations per bulk write request executed on - the follower + the follower. `indices[].parameters.max_write_request_size`:: (<>) 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`:: - (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`:: (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 - the number of queued operations goes below the limit + the number of queued operations goes below the limit. `indices[].parameters.max_write_buffer_size`:: (<>) The maximum total bytes of operations that can be 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`:: (<>) The maximum time to wait before retrying an operation that failed exceptionally. An exponential backoff strategy is - employed when retrying + employed when retrying. `indices[].parameters.read_poll_timeout`:: (<>) 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 returns to the follower 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 - -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 +[[ccr-get-follow-info-examples]] +==== {api-examples-title} This example retrieves follower info: diff --git a/docs/reference/ccr/apis/follow/get-follow-stats.asciidoc b/docs/reference/ccr/apis/follow/get-follow-stats.asciidoc index db4bf910a05..eeb5c1a7797 100644 --- a/docs/reference/ccr/apis/follow/get-follow-stats.asciidoc +++ b/docs/reference/ccr/apis/follow/get-follow-stats.asciidoc @@ -8,12 +8,8 @@ Get follower stats. -==== Description - -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 +[[ccr-get-follow-stats-request]] +==== {api-request-title} ////////////////////////// @@ -45,148 +41,167 @@ GET //_ccr/stats // CONSOLE // TEST[s//follower_index/] -==== Path Parameters -`index` :: - (string) a comma-delimited list of index patterns +[[ccr-get-follow-stats-prereqs]] +==== {api-prereq-title} -==== 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} + +`` (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: `indices`:: - (array) an array of follower index statistics + (array) An array of follower index statistics. The `indices` array consists of objects containing two fields: `indices[].index`:: - (string) the name of the follower index + (string) The name of the follower index. `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: `indices[].shards[].remote_cluster`:: - (string) the > containing the leader - index + (string) The > containing the 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`:: - (string) the name of the follower index + (string) The name of the follower index. `indices[].shards[].shard_id`:: - (integer) the numerical shard ID, with values from 0 to one less than the - number of replicas + (integer) The numerical shard ID, with values from 0 to one less than the + number of replicas. `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`:: - (long) the current maximum sequence number on the leader known to the follower - task + (long) The current maximum sequence number on the leader known to the follower + task. `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 - 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`:: - (long) the current maximum sequence number on the follower + (long) The current maximum sequence number on the follower. `indices[].shards[].last_requested_seq_no`:: - (long) the starting sequence number of the last batch of operations requested - from the leader + (long) The starting sequence number of the last batch of operations requested + from the leader. `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`:: - (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`:: - (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`:: - (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`:: - (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`:: - (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`:: - (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 + (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. `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`:: - (long) the number of successful fetches + (long) The number of successful fetches. `indices[].shards[].failed_read_requests`:: - (long) the number of failed reads + (long) The number of failed reads. `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`:: - (long) the total of transferred bytes read from the leader (note this is only - an estimate, and does not account for compression if enabled) + (long) The total of transferred bytes read from the leader. ++ +-- +NOTE: This is only an estimate and does not account for compression if enabled. + +-- `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`:: - (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`:: - (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`:: - (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`:: - (long) the number of operations written on the follower + (long) The number of operations written on the follower. `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 fields: `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`:: - (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`:: - (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`: `indices[].shards[].time_since_last_read_millis`:: - (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 + (long) The number of milliseconds since a read request was sent to the leader. ++ +-- +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 - request will be sent to the leader + request will be sent to the leader. + +-- `indices[].fatal_exception`:: - (object) an object representing a fatal exception that cancelled the following - task; in this situation, the following task must be resumed manually with the - <> + (object) An object representing a fatal exception that cancelled the following + task. In this situation, the following task must be resumed manually with the + <>. -==== Authorization - -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 +[[ccr-get-follow-stats-examples]] +==== {api-examples-title} This example retrieves follower stats: diff --git a/docs/reference/ccr/apis/follow/post-forget-follower.asciidoc b/docs/reference/ccr/apis/follow/post-forget-follower.asciidoc index 50cefc82009..979148adc57 100644 --- a/docs/reference/ccr/apis/follow/post-forget-follower.asciidoc +++ b/docs/reference/ccr/apis/follow/post-forget-follower.asciidoc @@ -1,36 +1,15 @@ [role="xpack"] [testenv="platinum"] [[ccr-post-forget-follower]] -=== Forget Follower API +=== Forget follower API ++++ -Forget Follower +Forget follower ++++ Removes the follower retention leases from the leader. -==== Description - -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 <> (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 <> is invoked. - -==== Request +[[ccr-post-forget-follower-request]] +==== {api-request-title} ////////////////////////// @@ -89,33 +68,61 @@ POST //_ccr/forget_follower // TESTRESPONSE[s/"failed" : 0/"failed" : $body._shards.failed/] // TESTRESPONSE[s/"failures" : \[ \]/"failures" : $body._shards.failures/] -==== Path Parameters +[[ccr-post-forget-follower-prereqs]] +==== {api-prereq-title} -`leader_index` (required):: - (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 <> containing - the leader index - -==== Authorization - -If the {es} {security-features} are enabled, you must have `manage_leader_index` +* If the {es} {security-features} are enabled, you must have `manage_leader_index` index privileges for the leader index. For more information, see {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 <> (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 <> is invoked. + +[[ccr-post-forget-follower-path-parms]] +==== {api-path-parms-title} + +`` (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 <> containing + the leader index. + +[[ccr-post-forget-follower-examples]] +==== {api-examples-title} This example removes the follower retention leases for `follower_index` from `leader_index`. diff --git a/docs/reference/ccr/apis/follow/post-pause-follow.asciidoc b/docs/reference/ccr/apis/follow/post-pause-follow.asciidoc index 60de85cabdc..b234719c606 100644 --- a/docs/reference/ccr/apis/follow/post-pause-follow.asciidoc +++ b/docs/reference/ccr/apis/follow/post-pause-follow.asciidoc @@ -8,15 +8,8 @@ Pauses a follower index. -==== Description - -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 <>. Pausing and -resuming a follower index can be used to change the configuration of the -following task. - -==== Request +[[ccr-post-pause-follow-request]] +==== {api-request-title} ////////////////////////// @@ -41,20 +34,30 @@ POST //_ccr/pause_follow // CONSOLE // TEST[s//follower_index/] -==== Path Parameters +[[ccr-post-pause-follow-prereqs]] +==== {api-prereq-title} -`follower_index` (required):: - (string) the name of the follower index - - -==== 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, 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 <>. 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} + +`` (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`: diff --git a/docs/reference/ccr/apis/follow/post-resume-follow.asciidoc b/docs/reference/ccr/apis/follow/post-resume-follow.asciidoc index 279f4139cdd..19c10b51f87 100644 --- a/docs/reference/ccr/apis/follow/post-resume-follow.asciidoc +++ b/docs/reference/ccr/apis/follow/post-resume-follow.asciidoc @@ -8,14 +8,8 @@ Resumes a follower index. -==== Description - -This API resumes a follower index that has been paused either explicitly with -the <> 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 +[[ccr-post-resume-follow-request]] +==== {api-request-title} ////////////////////////// @@ -53,23 +47,35 @@ POST //_ccr/resume_follow // TEST[s//remote_cluster/] // TEST[s//leader_index/] -==== Path Parameters +[[ccr-post-resume-follow-prereqs]] +==== {api-prereq-title} -`follower_index` (required):: - (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` +* 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 leader index. You must also have `manage_ccr` cluster privileges on the cluster that contains the follower index. For more information, 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 <> 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} + +`` (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`: diff --git a/docs/reference/ccr/apis/follow/post-unfollow.asciidoc b/docs/reference/ccr/apis/follow/post-unfollow.asciidoc index 236d2723a94..405a3547a78 100644 --- a/docs/reference/ccr/apis/follow/post-unfollow.asciidoc +++ b/docs/reference/ccr/apis/follow/post-unfollow.asciidoc @@ -8,18 +8,8 @@ Converts a follower index to a regular index. -==== Description - -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 +[[ccr-post-unfollow-request]] +==== {api-request-title} ////////////////////////// @@ -48,18 +38,33 @@ POST //_ccr/unfollow // CONSOLE // TEST[s//follower_index/] -==== Path Parameters +[[ccr-post-unfollow-prereqs]] +==== {api-prereq-title} -`follower_index` (required):: - (string) the name of the follower index - -==== Authorization - -If the {es} {security-features} are enabled, you must have `manage_follow_index` +* If the {es} {security-features} are enabled, you must have `manage_follow_index` index privileges for the follower index. For more information, see {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} + +`` (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: diff --git a/docs/reference/ccr/apis/follow/put-follow.asciidoc b/docs/reference/ccr/apis/follow/put-follow.asciidoc index 8098fcff1cd..b5480681541 100644 --- a/docs/reference/ccr/apis/follow/put-follow.asciidoc +++ b/docs/reference/ccr/apis/follow/put-follow.asciidoc @@ -8,13 +8,8 @@ Creates a follower index. -==== Description - -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 +[[ccr-put-follow-request]] +==== {api-request-title} ////////////////////////// @@ -41,36 +36,54 @@ PUT //_ccr/follow?wait_for_active_shards=1 // TEST[s//remote_cluster/] // TEST[s//leader_index/] -The `wait_for_active_shards` parameter 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-prereqs]] +==== {api-prereq-title} -==== Path Parameters - -`follower_index` (required):: - (string) the name of the follower index - -==== Request Body -`remote_cluster` (required):: - (string) the <> 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`, +* 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 `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 {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} + +`` (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 <> 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`: diff --git a/docs/reference/ccr/apis/get-ccr-stats.asciidoc b/docs/reference/ccr/apis/get-ccr-stats.asciidoc index d1acbb0064a..37625ae5b1c 100644 --- a/docs/reference/ccr/apis/get-ccr-stats.asciidoc +++ b/docs/reference/ccr/apis/get-ccr-stats.asciidoc @@ -2,19 +2,15 @@ [testenv="platinum"] [[ccr-get-stats]] === Get {ccr} stats API +[subs="attributes"] ++++ -Get CCR stats +Get {ccr-init} stats ++++ Get {ccr} stats. -==== Description - -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 <>. - -==== Request +[[ccr-get-stats-request]] +==== {api-request-title} ////////////////////////// @@ -45,46 +41,55 @@ GET /_ccr/stats -------------------------------------------------- // 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-stats-response-body]] +==== {api-response-body-title} This API returns the following information: `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: `auto_follow_stats.number_of_failed_follow_indices`:: - (long) the number of indices that the auto-follow coordinator failed to - automatically follow; the causes of recent failures are captured in the logs - of the elected master node, and in the - `auto_follow_stats.recent_auto_follow_errors` field + (long) The number of indices that the auto-follow coordinator failed to + automatically follow. The causes of recent failures are captured in the logs + of the elected master node and in the + `auto_follow_stats.recent_auto_follow_errors` field. `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 - auto-follow patterns + auto-follow patterns. `auto_follow_stats.number_of_successful_follow_indices`:: - (long) the number of indices that the auto-follow coordinator successfully - followed + (long) The number of indices that the auto-follow coordinator successfully + followed. `auto_follow_stats.recent_auto_follow_errors`:: - (array) an array of objects representing failures by the auto-follow - coordinator + (array) An array of objects representing failures by the auto-follow + coordinator. `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 - <> + <>. -==== Authorization - -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 +[[ccr-get-stats-examples]] +==== {api-examples-title} This example retrieves {ccr} stats: