Skip to content

Commit eac084c

Browse files
jasontedorkcm
jasontedor
authored and
kcm
committed
Introduce cross-cluster replication API docs (#34726)
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.
1 parent d5d2335 commit eac084c

17 files changed

+1040
-1
lines changed

‎docs/build.gradle

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,6 @@ buildRestTests.setups['host'] = '''
139139
- do:
140140
nodes.info:
141141
metric: [ http, transport ]
142-
- is_true: nodes.$master.http.publish_address
143142
- set: {nodes.$master.http.publish_address: host}
144143
- set: {nodes.$master.transport.publish_address: transport_host}
145144
'''
@@ -1083,4 +1082,21 @@ buildRestTests.setups['calendar_outages_addevent'] = buildRestTests.setups['cale
10831082
]}
10841083
'''
10851084

1085+
buildRestTests.setups['remote_cluster'] = buildRestTests.setups['host'] + '''
1086+
- do:
1087+
cluster.put_settings:
1088+
body:
1089+
persistent:
1090+
cluster.remote.remote_cluster.seeds: $transport_host
1091+
'''
10861092

1093+
buildRestTests.setups['remote_cluster_and_leader_index'] = buildRestTests.setups['remote_cluster'] + '''
1094+
- do:
1095+
indices.create:
1096+
index: leader_index
1097+
body:
1098+
settings:
1099+
index.number_of_replicas: 0
1100+
index.number_of_shards: 1
1101+
index.soft_deletes.enabled: true
1102+
'''

‎docs/reference/ccr/apis/auto-follow/delete-auto-follow-pattern.asciidoc

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
[role="xpack"]
2+
[testenv="platinum"]
3+
[[ccr-delete-auto-follow-pattern]]
4+
=== Delete Auto-Follow Pattern API
5+
++++
6+
<titleabbrev>Delete Auto-Follow Pattern</titleabbrev>
7+
++++
8+
9+
Delete auto-follow patterns.
10+
11+
==== Description
12+
13+
This API deletes a configured auto-follow pattern collection.
14+
15+
==== Request
16+
17+
//////////////////////////
18+
19+
[source,js]
20+
--------------------------------------------------
21+
PUT /_ccr/auto_follow/my_auto_follow_pattern
22+
{
23+
"remote_cluster" : "remote_cluster",
24+
"leader_index_patterns" :
25+
[
26+
"leader_index"
27+
],
28+
"follow_index_pattern" : "{{leader_index}}-follower"
29+
}
30+
--------------------------------------------------
31+
// CONSOLE
32+
// TEST[setup:remote_cluster]
33+
// TESTSETUP
34+
35+
//////////////////////////
36+
37+
[source,js]
38+
--------------------------------------------------
39+
DELETE /_ccr/auto_follow/<auto_follow_pattern_name>
40+
--------------------------------------------------
41+
// CONSOLE
42+
// TEST[s/<auto_follow_pattern_name>/my_auto_follow_pattern/]
43+
44+
==== Path Parameters
45+
`auto_follow_pattern_name` (required)::
46+
(string) specifies the auto-follow pattern collection to delete
47+
48+
==== Example
49+
50+
This example deletes an auto-follow pattern collection named
51+
`my_auto_follow_pattern`:
52+
53+
[source,js]
54+
--------------------------------------------------
55+
DELETE /_ccr/auto_follow/my_auto_follow_pattern
56+
--------------------------------------------------
57+
// CONSOLE
58+
// TEST[setup:remote_cluster]
59+
60+
The API returns the following result:
61+
62+
[source,js]
63+
--------------------------------------------------
64+
{
65+
"acknowledged" : true
66+
}
67+
--------------------------------------------------
68+
// TESTRESPONSE

‎docs/reference/ccr/apis/auto-follow/get-auto-follow-pattern.asciidoc

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
[role="xpack"]
2+
[testenv="platinum"]
3+
[[ccr-get-auto-follow-pattern]]
4+
=== Get Auto-Follow Pattern API
5+
++++
6+
<titleabbrev>Get Auto-Follow Pattern</titleabbrev>
7+
++++
8+
9+
Get auto-follow patterns.
10+
11+
==== Description
12+
13+
This API gets configured auto-follow patterns. This API will return the
14+
specified auto-follow pattern collection.
15+
16+
==== Request
17+
18+
//////////////////////////
19+
20+
[source,js]
21+
--------------------------------------------------
22+
PUT /_ccr/auto_follow/my_auto_follow_pattern
23+
{
24+
"remote_cluster" : "remote_cluster",
25+
"leader_index_patterns" :
26+
[
27+
"leader_index*"
28+
],
29+
"follow_index_pattern" : "{{leader_index}}-follower"
30+
}
31+
--------------------------------------------------
32+
// CONSOLE
33+
// TEST[setup:remote_cluster]
34+
// TESTSETUP
35+
36+
[source,js]
37+
--------------------------------------------------
38+
DELETE /_ccr/auto_follow/my_auto_follow_pattern
39+
--------------------------------------------------
40+
// CONSOLE
41+
// TEST
42+
// TEARDOWN
43+
44+
//////////////////////////
45+
46+
[source,js]
47+
--------------------------------------------------
48+
GET /_ccr/auto_follow/
49+
--------------------------------------------------
50+
// CONSOLE
51+
52+
[source,js]
53+
--------------------------------------------------
54+
GET /_ccr/auto_follow/<auto_follow_pattern_name>
55+
--------------------------------------------------
56+
// CONSOLE
57+
// TEST[s/<auto_follow_pattern_name>/my_auto_follow_pattern/]
58+
59+
==== Path Parameters
60+
`auto_follow_pattern_name`::
61+
(string) specifies the auto-follow pattern collection that you want to
62+
retrieve; if you do not specify a name, the API returns information for all
63+
collections
64+
65+
==== Example
66+
67+
This example retrieves information about an auto-follow pattern collection
68+
named `my_auto_follow_pattern`:
69+
70+
[source,js]
71+
--------------------------------------------------
72+
GET /_ccr/auto_follow/my_auto_follow_pattern
73+
--------------------------------------------------
74+
// CONSOLE
75+
// TEST[setup:remote_cluster]
76+
77+
The API returns the following result:
78+
79+
[source,js]
80+
--------------------------------------------------
81+
{
82+
"my_auto_follow_pattern" :
83+
{
84+
"remote_cluster" : "remote_cluster",
85+
"leader_index_patterns" :
86+
[
87+
"leader_index*"
88+
],
89+
"follow_index_pattern" : "{{leader_index}}-follower"
90+
}
91+
}
92+
--------------------------------------------------
93+
// TESTRESPONSE

‎docs/reference/ccr/apis/auto-follow/get-auto-follow-stats.asciidoc

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
[role="xpack"]
2+
[testenv="platinum"]
3+
[[ccr-get-auto-follow-stats]]
4+
=== Get Auto-Follow Stats API
5+
++++
6+
<titleabbrev>Get Auto-Follow Stats</titleabbrev>
7+
++++
8+
9+
Get auto-follow stats.
10+
11+
==== Description
12+
13+
This API gets stats about auto-follow patterns.
14+
15+
==== Request
16+
17+
[source,js]
18+
--------------------------------------------------
19+
GET /_ccr/auto_follow/stats
20+
--------------------------------------------------
21+
// CONSOLE
22+
// TEST
23+
24+
==== Example
25+
26+
This example retrieves stats about auto-follow patterns:
27+
28+
[source,js]
29+
--------------------------------------------------
30+
GET /_ccr/auto_follow/stats
31+
--------------------------------------------------
32+
// CONSOLE
33+
// TEST
34+
35+
The API returns the following result:
36+
37+
[source,js]
38+
--------------------------------------------------
39+
{
40+
"number_of_successful_follow_indices" : 16,
41+
"number_of_failed_follow_indices" : 0,
42+
"number_of_failed_remote_cluster_state_requests" : 0,
43+
"recent_auto_follow_errors" : [ ]
44+
}
45+
--------------------------------------------------
46+
// TESTRESPONSE[s/"number_of_successful_follow_indices" : 16/"number_of_successful_follow_indices" : $body.number_of_successful_follow_indices/]

‎docs/reference/ccr/apis/auto-follow/put-auto-follow-pattern.asciidoc

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
[role="xpack"]
2+
[testenv="platinum"]
3+
[[ccr-put-auto-follow-pattern]]
4+
=== Create Auto-Follow Pattern API
5+
++++
6+
<titleabbrev>Create Auto-Follow Pattern</titleabbrev>
7+
++++
8+
9+
Creates an auto-follow pattern.
10+
11+
==== Description
12+
13+
This API creates a new named collection of auto-follow patterns against the
14+
remote cluster specified in the request body. Newly created indices on the
15+
remote cluster matching any of the specified patterns will be automatically
16+
configured as follower indices.
17+
18+
==== Request
19+
20+
[source,js]
21+
--------------------------------------------------
22+
PUT /_ccr/auto_follow/<auto_follow_pattern_name>
23+
{
24+
"remote_cluster" : "<remote_cluster>",
25+
"leader_index_patterns" :
26+
[
27+
"<leader_index_pattern>"
28+
],
29+
"follow_index_pattern" : "<follow_index_pattern>"
30+
}
31+
--------------------------------------------------
32+
// CONSOLE
33+
// TEST[setup:remote_cluster]
34+
// TEST[s/<auto_follow_pattern_name>/auto_follow_pattern_name/]
35+
// TEST[s/<remote_cluster>/remote_cluster/]
36+
// TEST[s/<leader_index_patterns>/leader_index*/]
37+
// TEST[s/<follow_index_pattern>/{{leader_index}}-follower/]
38+
39+
//////////////////////////
40+
41+
[source,js]
42+
--------------------------------------------------
43+
DELETE /_ccr/auto_follow/auto_follow_pattern_name
44+
--------------------------------------------------
45+
// CONSOLE
46+
// TEST[continued]
47+
48+
//////////////////////////
49+
50+
==== Path Parameters
51+
`auto_follow_pattern_name` (required)::
52+
(string) name of the collection of auto-follow patterns
53+
54+
==== Request Body
55+
`remote_cluster`::
56+
(required string) the <<modules-remote-clusters,remote cluster>> containing the
57+
leader indices to match against
58+
59+
`leader_index_patterns`::
60+
(array) an array of simple index patterns to match against indices in the
61+
remote cluster specified by the `remote_cluster` field
62+
63+
`follow_index_pattern`::
64+
(string) the name of follower index; the template `{{leader_index}}` can be
65+
used to derive the name of the follower index from the name of the leader
66+
index
67+
68+
include::../follow-request-body.asciidoc[]
69+
70+
==== Example
71+
72+
This example creates an auto-follow pattern named `my_auto_follow_pattern`:
73+
74+
[source,js]
75+
--------------------------------------------------
76+
PUT /_ccr/auto_follow/my_auto_follow_pattern
77+
{
78+
"remote_cluster" : "remote_cluster",
79+
"leader_index_patterns" :
80+
[
81+
"leader_index*"
82+
],
83+
"follow_index_pattern" : "{{leader_index}}-follower",
84+
"max_read_request_operation_count" : 1024,
85+
"max_outstanding_read_requests" : 16,
86+
"max_read_request_size" : "1024k",
87+
"max_write_request_operation_count" : 32768,
88+
"max_write_request_size" : "16k",
89+
"max_outstanding_write_requests" : 8,
90+
"max_write_buffer_count" : 512,
91+
"max_write_buffer_size" : "512k",
92+
"max_retry_delay" : "10s",
93+
"read_poll_timeout" : "30s"
94+
}
95+
--------------------------------------------------
96+
// CONSOLE
97+
// TEST[setup:remote_cluster]
98+
99+
The API returns the following result:
100+
101+
[source,js]
102+
--------------------------------------------------
103+
{
104+
"acknowledged" : true
105+
}
106+
--------------------------------------------------
107+
// TESTRESPONSE
108+
109+
//////////////////////////
110+
111+
[source,js]
112+
--------------------------------------------------
113+
DELETE /_ccr/auto_follow/my_auto_follow_pattern
114+
--------------------------------------------------
115+
// CONSOLE
116+
// TEST[continued]
117+
118+
//////////////////////////

‎docs/reference/ccr/apis/ccr-apis.asciidoc

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
[role="xpack"]
2+
[testenv="platinum"]
3+
[[ccr-apis]]
4+
== Cross-cluster replication APIs
5+
6+
You can use the following APIs to perform {ccr} operations.
7+
8+
[float]
9+
[[ccr-api-follow]]
10+
=== Follow
11+
12+
* <<ccr-put-follow,Create follower index>>
13+
* <<ccr-post-pause-follow,Pause follower>>
14+
* <<ccr-post-resume-follow,Resume follower>>
15+
* <<ccr-post-unfollow,Convert follower index to a regular index>>
16+
* <<ccr-get-follow-stats,Get stats about follower indices>>
17+
18+
[float]
19+
[[ccr-api-auto-follow]]
20+
=== Auto-follow
21+
22+
* <<ccr-put-auto-follow-pattern,Create auto-follow pattern>>
23+
* <<ccr-delete-auto-follow-pattern,Delete auto-follow pattern>>
24+
* <<ccr-get-auto-follow-pattern,Get auto-follow patterns>>
25+
* <<ccr-get-auto-follow-stats,Get stats about auto-follow patterns>>
26+
27+
// follow
28+
include::follow/put-follow.asciidoc[]
29+
include::follow/post-pause-follow.asciidoc[]
30+
include::follow/post-resume-follow.asciidoc[]
31+
include::follow/post-unfollow.asciidoc[]
32+
include::follow/get-follow-stats.asciidoc[]
33+
34+
// auto-follow
35+
include::auto-follow/put-auto-follow-pattern.asciidoc[]
36+
include::auto-follow/delete-auto-follow-pattern.asciidoc[]
37+
include::auto-follow/get-auto-follow-pattern.asciidoc[]
38+
include::auto-follow/get-auto-follow-stats.asciidoc[]

0 commit comments

Comments
 (0)