Skip to content

Commit

Permalink
Introduce cross-cluster replication API docs (elastic#34726)
Browse files Browse the repository at this point in the history
This commit is our first introduction to cross-cluster replication
docs. In this commit, we introduce the cross-cluster replication API
docs. We also add skelton docs for additional content that will be added
in a series of follow-up commits.
  • Loading branch information
jasontedor authored Oct 26, 2018
1 parent a0279bc commit fdfdbe4
Show file tree
Hide file tree
Showing 17 changed files with 1,040 additions and 1 deletion.
18 changes: 17 additions & 1 deletion docs/build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,6 @@ buildRestTests.setups['host'] = '''
- do:
nodes.info:
metric: [ http, transport ]
- is_true: nodes.$master.http.publish_address
- set: {nodes.$master.http.publish_address: host}
- set: {nodes.$master.transport.publish_address: transport_host}
'''
Expand Down Expand Up @@ -1083,4 +1082,21 @@ buildRestTests.setups['calendar_outages_addevent'] = buildRestTests.setups['cale
]}
'''

buildRestTests.setups['remote_cluster'] = buildRestTests.setups['host'] + '''
- do:
cluster.put_settings:
body:
persistent:
cluster.remote.remote_cluster.seeds: $transport_host
'''

buildRestTests.setups['remote_cluster_and_leader_index'] = buildRestTests.setups['remote_cluster'] + '''
- do:
indices.create:
index: leader_index
body:
settings:
index.number_of_replicas: 0
index.number_of_shards: 1
index.soft_deletes.enabled: true
'''
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
[role="xpack"]
[testenv="platinum"]
[[ccr-delete-auto-follow-pattern]]
=== Delete Auto-Follow Pattern API
++++
<titleabbrev>Delete Auto-Follow Pattern</titleabbrev>
++++

Delete auto-follow patterns.

==== Description

This API deletes a configured auto-follow pattern collection.

==== Request

//////////////////////////
[source,js]
--------------------------------------------------
PUT /_ccr/auto_follow/my_auto_follow_pattern
{
"remote_cluster" : "remote_cluster",
"leader_index_patterns" :
[
"leader_index"
],
"follow_index_pattern" : "{{leader_index}}-follower"
}
--------------------------------------------------
// CONSOLE
// TEST[setup:remote_cluster]
// TESTSETUP
//////////////////////////

[source,js]
--------------------------------------------------
DELETE /_ccr/auto_follow/<auto_follow_pattern_name>
--------------------------------------------------
// CONSOLE
// TEST[s/<auto_follow_pattern_name>/my_auto_follow_pattern/]

==== Path Parameters
`auto_follow_pattern_name` (required)::
(string) specifies the auto-follow pattern collection to delete

==== Example

This example deletes an auto-follow pattern collection named
`my_auto_follow_pattern`:

[source,js]
--------------------------------------------------
DELETE /_ccr/auto_follow/my_auto_follow_pattern
--------------------------------------------------
// CONSOLE
// TEST[setup:remote_cluster]

The API returns the following result:

[source,js]
--------------------------------------------------
{
"acknowledged" : true
}
--------------------------------------------------
// TESTRESPONSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
[role="xpack"]
[testenv="platinum"]
[[ccr-get-auto-follow-pattern]]
=== Get Auto-Follow Pattern API
++++
<titleabbrev>Get Auto-Follow Pattern</titleabbrev>
++++

Get auto-follow patterns.

==== Description

This API gets configured auto-follow patterns. This API will return the
specified auto-follow pattern collection.

==== Request

//////////////////////////
[source,js]
--------------------------------------------------
PUT /_ccr/auto_follow/my_auto_follow_pattern
{
"remote_cluster" : "remote_cluster",
"leader_index_patterns" :
[
"leader_index*"
],
"follow_index_pattern" : "{{leader_index}}-follower"
}
--------------------------------------------------
// CONSOLE
// TEST[setup:remote_cluster]
// TESTSETUP
[source,js]
--------------------------------------------------
DELETE /_ccr/auto_follow/my_auto_follow_pattern
--------------------------------------------------
// CONSOLE
// TEST
// TEARDOWN
//////////////////////////

[source,js]
--------------------------------------------------
GET /_ccr/auto_follow/
--------------------------------------------------
// CONSOLE

[source,js]
--------------------------------------------------
GET /_ccr/auto_follow/<auto_follow_pattern_name>
--------------------------------------------------
// CONSOLE
// TEST[s/<auto_follow_pattern_name>/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

==== Example

This example retrieves information about an auto-follow pattern collection
named `my_auto_follow_pattern`:

[source,js]
--------------------------------------------------
GET /_ccr/auto_follow/my_auto_follow_pattern
--------------------------------------------------
// CONSOLE
// TEST[setup:remote_cluster]

The API returns the following result:

[source,js]
--------------------------------------------------
{
"my_auto_follow_pattern" :
{
"remote_cluster" : "remote_cluster",
"leader_index_patterns" :
[
"leader_index*"
],
"follow_index_pattern" : "{{leader_index}}-follower"
}
}
--------------------------------------------------
// TESTRESPONSE
46 changes: 46 additions & 0 deletions docs/reference/ccr/apis/auto-follow/get-auto-follow-stats.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
[role="xpack"]
[testenv="platinum"]
[[ccr-get-auto-follow-stats]]
=== Get Auto-Follow Stats API
++++
<titleabbrev>Get Auto-Follow Stats</titleabbrev>
++++

Get auto-follow stats.

==== Description

This API gets stats about auto-follow patterns.

==== Request

[source,js]
--------------------------------------------------
GET /_ccr/auto_follow/stats
--------------------------------------------------
// CONSOLE
// TEST

==== Example

This example retrieves stats about auto-follow patterns:

[source,js]
--------------------------------------------------
GET /_ccr/auto_follow/stats
--------------------------------------------------
// CONSOLE
// TEST

The API returns the following result:

[source,js]
--------------------------------------------------
{
"number_of_successful_follow_indices" : 16,
"number_of_failed_follow_indices" : 0,
"number_of_failed_remote_cluster_state_requests" : 0,
"recent_auto_follow_errors" : [ ]
}
--------------------------------------------------
// TESTRESPONSE[s/"number_of_successful_follow_indices" : 16/"number_of_successful_follow_indices" : $body.number_of_successful_follow_indices/]
118 changes: 118 additions & 0 deletions docs/reference/ccr/apis/auto-follow/put-auto-follow-pattern.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
[role="xpack"]
[testenv="platinum"]
[[ccr-put-auto-follow-pattern]]
=== Create Auto-Follow Pattern API
++++
<titleabbrev>Create Auto-Follow Pattern</titleabbrev>
++++

Creates an auto-follow pattern.

==== Description

This API creates a new named collection of 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]
--------------------------------------------------
PUT /_ccr/auto_follow/<auto_follow_pattern_name>
{
"remote_cluster" : "<remote_cluster>",
"leader_index_patterns" :
[
"<leader_index_pattern>"
],
"follow_index_pattern" : "<follow_index_pattern>"
}
--------------------------------------------------
// CONSOLE
// TEST[setup:remote_cluster]
// TEST[s/<auto_follow_pattern_name>/auto_follow_pattern_name/]
// TEST[s/<remote_cluster>/remote_cluster/]
// TEST[s/<leader_index_patterns>/leader_index*/]
// TEST[s/<follow_index_pattern>/{{leader_index}}-follower/]

//////////////////////////
[source,js]
--------------------------------------------------
DELETE /_ccr/auto_follow/auto_follow_pattern_name
--------------------------------------------------
// CONSOLE
// TEST[continued]
//////////////////////////

==== Path Parameters
`auto_follow_pattern_name` (required)::
(string) name of the collection of auto-follow patterns

==== Request Body
`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[]

==== Example

This example creates an auto-follow pattern named `my_auto_follow_pattern`:

[source,js]
--------------------------------------------------
PUT /_ccr/auto_follow/my_auto_follow_pattern
{
"remote_cluster" : "remote_cluster",
"leader_index_patterns" :
[
"leader_index*"
],
"follow_index_pattern" : "{{leader_index}}-follower",
"max_read_request_operation_count" : 1024,
"max_outstanding_read_requests" : 16,
"max_read_request_size" : "1024k",
"max_write_request_operation_count" : 32768,
"max_write_request_size" : "16k",
"max_outstanding_write_requests" : 8,
"max_write_buffer_count" : 512,
"max_write_buffer_size" : "512k",
"max_retry_delay" : "10s",
"read_poll_timeout" : "30s"
}
--------------------------------------------------
// CONSOLE
// TEST[setup:remote_cluster]

The API returns the following result:

[source,js]
--------------------------------------------------
{
"acknowledged" : true
}
--------------------------------------------------
// TESTRESPONSE

//////////////////////////
[source,js]
--------------------------------------------------
DELETE /_ccr/auto_follow/my_auto_follow_pattern
--------------------------------------------------
// CONSOLE
// TEST[continued]
//////////////////////////
38 changes: 38 additions & 0 deletions docs/reference/ccr/apis/ccr-apis.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
[role="xpack"]
[testenv="platinum"]
[[ccr-apis]]
== Cross-cluster replication APIs

You can use the following APIs to perform {ccr} operations.

[float]
[[ccr-api-follow]]
=== Follow

* <<ccr-put-follow,Create follower index>>
* <<ccr-post-pause-follow,Pause follower>>
* <<ccr-post-resume-follow,Resume follower>>
* <<ccr-post-unfollow,Convert follower index to a regular index>>
* <<ccr-get-follow-stats,Get stats about follower indices>>

[float]
[[ccr-api-auto-follow]]
=== Auto-follow

* <<ccr-put-auto-follow-pattern,Create auto-follow pattern>>
* <<ccr-delete-auto-follow-pattern,Delete auto-follow pattern>>
* <<ccr-get-auto-follow-pattern,Get auto-follow patterns>>
* <<ccr-get-auto-follow-stats,Get stats about auto-follow patterns>>

// follow
include::follow/put-follow.asciidoc[]
include::follow/post-pause-follow.asciidoc[]
include::follow/post-resume-follow.asciidoc[]
include::follow/post-unfollow.asciidoc[]
include::follow/get-follow-stats.asciidoc[]

// auto-follow
include::auto-follow/put-auto-follow-pattern.asciidoc[]
include::auto-follow/delete-auto-follow-pattern.asciidoc[]
include::auto-follow/get-auto-follow-pattern.asciidoc[]
include::auto-follow/get-auto-follow-stats.asciidoc[]
Loading

0 comments on commit fdfdbe4

Please sign in to comment.