Skip to content

Commit fe15d9f

Browse files
tlrxjrodewig
tlrx
and
jrodewig
authored
Add documentation for Pause/Resume Auto-Follower APIs (#47985) (#48034)
Relates #47510 Co-Authored-By: James Rodewig <[email protected]>
1 parent 9843237 commit fe15d9f

File tree

4 files changed

+171
-2
lines changed

4 files changed

+171
-2
lines changed

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

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
[role="xpack"]
2+
[testenv="platinum"]
3+
[[ccr-pause-auto-follow-pattern]]
4+
=== Pause auto-follow pattern API
5+
++++
6+
<titleabbrev>Pause auto-follow pattern</titleabbrev>
7+
++++
8+
9+
Pauses an auto-follow pattern.
10+
11+
[[ccr-pause-auto-follow-pattern-request]]
12+
==== {api-request-title}
13+
14+
`POST /_ccr/auto_follow/<auto_follow_pattern_name>/pause`
15+
16+
[[ccr-pause-auto-follow-pattern-prereqs]]
17+
==== {api-prereq-title}
18+
19+
* If the {es} {security-features} are enabled, you must have `manage_ccr` cluster
20+
privileges on the cluster that contains the follower index. For more information,
21+
see <<security-privileges>>.
22+
23+
[[ccr-pause-auto-follow-pattern-desc]]
24+
==== {api-description-title}
25+
26+
This API pauses an <<ccr-auto-follow,auto-follow pattern>>. When this API returns, the auto-follow pattern
27+
is inactive and ignores any new index created on the remote cluster that matches any of
28+
the auto-follow's patterns. Paused auto-follow patterns appear with the `active` field
29+
set to `false` in the <<ccr-get-auto-follow-pattern, GET auto-follow patterns API>>.
30+
31+
You can resume auto-following with the <<ccr-resume-auto-follow-pattern,resume auto-follow pattern API>>.
32+
Once resumed, the auto-follow pattern is active again and automatically configure
33+
follower indices for newly created indices on the remote cluster that match its patterns.
34+
Remote indices created while the
35+
pattern was paused will also be followed, unless they have been deleted or closed in the
36+
meantime.
37+
38+
[[ccr-pause-auto-follow-pattern-path-parms]]
39+
==== {api-path-parms-title}
40+
41+
`<auto_follow_pattern_name>`::
42+
(Required, string) Name of the auto-follow pattern to pause.
43+
44+
45+
[[ccr-pause-auto-follow-pattern-examples]]
46+
==== {api-examples-title}
47+
48+
This example pauses an auto-follow pattern named `my_auto_follow_pattern`:
49+
//////////////////////////
50+
51+
[source,console]
52+
--------------------------------------------------
53+
PUT /_ccr/auto_follow/my_auto_follow_pattern
54+
{
55+
"remote_cluster" : "remote_cluster",
56+
"leader_index_patterns" :
57+
[
58+
"leader_index"
59+
],
60+
"follow_index_pattern" : "{{leader_index}}-follower"
61+
}
62+
--------------------------------------------------
63+
// TEST[setup:remote_cluster]
64+
// TESTSETUP
65+
66+
//////////////////////////
67+
68+
[source,console]
69+
--------------------------------------------------
70+
POST /_ccr/auto_follow/my_auto_follow_pattern/pause
71+
--------------------------------------------------
72+
// TEST
73+
74+
The API returns the following result:
75+
76+
[source,console-result]
77+
--------------------------------------------------
78+
{
79+
"acknowledged" : true
80+
}
81+
--------------------------------------------------

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

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
[role="xpack"]
2+
[testenv="platinum"]
3+
[[ccr-resume-auto-follow-pattern]]
4+
=== Resume auto-follow pattern API
5+
++++
6+
<titleabbrev>Resume auto-follow pattern</titleabbrev>
7+
++++
8+
9+
Resumes an auto-follow pattern.
10+
11+
[[ccr-resume-auto-follow-pattern-request]]
12+
==== {api-request-title}
13+
14+
`POST /_ccr/auto_follow/<auto_follow_pattern_name>/resume`
15+
16+
[[ccr-resume-auto-follow-pattern-prereqs]]
17+
==== {api-prereq-title}
18+
19+
* If the {es} {security-features} are enabled, you must have `manage_ccr` cluster
20+
privileges on the cluster that contains the follower index. For more information,
21+
see <<security-privileges>>.
22+
23+
[[ccr-resume-auto-follow-pattern-desc]]
24+
==== {api-description-title}
25+
26+
This API resumes an <<ccr-auto-follow,auto-follow pattern>> that has been paused with the
27+
<<ccr-pause-auto-follow-pattern, pause auto-follow pattern API>>. When this API
28+
returns, the auto-follow pattern will resume configuring following indices for
29+
newly created indices on the remote cluster that match its patterns. Remote
30+
indices created while the pattern was paused will also be followed, unless they
31+
have been deleted or closed in the meantime.
32+
33+
[[ccr-resume-auto-follow-pattern-path-parms]]
34+
==== {api-path-parms-title}
35+
36+
`<auto_follow_pattern_name>`::
37+
(Required, string) Specifies the name of the auto-follow pattern to resume.
38+
39+
40+
[[ccr-resume-auto-follow-pattern-examples]]
41+
==== {api-examples-title}
42+
43+
This example resumes the activity of a paused auto-follow pattern
44+
named `my_auto_follow_pattern`:
45+
//////////////////////////
46+
47+
[source,console]
48+
--------------------------------------------------
49+
PUT /_ccr/auto_follow/my_auto_follow_pattern
50+
{
51+
"remote_cluster" : "remote_cluster",
52+
"leader_index_patterns" :
53+
[
54+
"leader_index"
55+
],
56+
"follow_index_pattern" : "{{leader_index}}-follower"
57+
}
58+
--------------------------------------------------
59+
// TEST[setup:remote_cluster]
60+
// TESTSETUP
61+
62+
[source,console]
63+
--------------------------------------------------
64+
POST /_ccr/auto_follow/my_auto_follow_pattern/pause
65+
--------------------------------------------------
66+
// TEST
67+
68+
//////////////////////////
69+
[source,console]
70+
--------------------------------------------------
71+
POST /_ccr/auto_follow/my_auto_follow_pattern/resume
72+
--------------------------------------------------
73+
// TEST
74+
75+
The API returns the following result:
76+
77+
[source,console-result]
78+
--------------------------------------------------
79+
{
80+
"acknowledged" : true
81+
}
82+
--------------------------------------------------

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

+4
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ You can use the following APIs to perform {ccr} operations.
3030
* <<ccr-put-auto-follow-pattern,Create auto-follow pattern>>
3131
* <<ccr-delete-auto-follow-pattern,Delete auto-follow pattern>>
3232
* <<ccr-get-auto-follow-pattern,Get auto-follow patterns>>
33+
* <<ccr-pause-auto-follow-pattern,Pause auto-follow pattern>>
34+
* <<ccr-resume-auto-follow-pattern,Resume auto-follow pattern>>
3335

3436
// top-level
3537
include::get-ccr-stats.asciidoc[]
@@ -47,3 +49,5 @@ include::follow/get-follow-info.asciidoc[]
4749
include::auto-follow/put-auto-follow-pattern.asciidoc[]
4850
include::auto-follow/delete-auto-follow-pattern.asciidoc[]
4951
include::auto-follow/get-auto-follow-pattern.asciidoc[]
52+
include::auto-follow/pause-auto-follow-pattern.asciidoc[]
53+
include::auto-follow/resume-auto-follow-pattern.asciidoc[]

‎docs/reference/ccr/auto-follow.asciidoc

+4-2
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,10 @@ a follower index is configured in the local cluster. The follower index uses the
2121
new index as its leader index.
2222

2323
You can inspect all configured auto-follow pattern collections with the
24-
{ref}/ccr-get-auto-follow-pattern.html[get auto-follow pattern API]. To delete a
25-
configured auto-follow pattern collection, use the
24+
{ref}/ccr-get-auto-follow-pattern.html[get auto-follow pattern API]. Auto-follow patterns
25+
can be paused using the {ref}/ccr-pause-auto-follow-pattern.html[pause auto-follow pattern API]
26+
and can be resumed using the {ref}/ccr-resume-auto-follow-pattern.html[resume auto-follow pattern API].
27+
To delete a configured auto-follow pattern collection, use the
2628
{ref}/ccr-delete-auto-follow-pattern.html[delete auto-follow pattern API].
2729

2830
Since auto-follow functionality is handled automatically in the background on

0 commit comments

Comments
 (0)