Introduce cross-cluster replication API docs (elastic#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.

docs/build.gradle

@@ -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}
 '''
@@ -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
+'''

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

@@ -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

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

@@ -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

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

@@ -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/]

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

@@ -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]
+
+//////////////////////////

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

@@ -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[]