Browse Source

[DOCS] Add prerequisites for CCS (#81782)

* Adds a prerequisites section covering remote cluster config, node roles, and security.
* Moves existing content about remote cluster config to the prereqs.
* Updates the remote cluster docs to include information about eligible gateway nodes and tagging for gateway nodes.

Closes https://github.com/elastic/elasticsearch/issues/72001
James Rodewig 3 years ago
parent
commit
7142b47e69

+ 1 - 0
docs/reference/modules/cluster/remote-clusters-settings.asciidoc

@@ -76,6 +76,7 @@ mode are described separately.
   The number of gateway nodes to connect to for this remote cluster. The default
   is `3`.
 
+[[cluster-remote-node-attr]]
 `cluster.remote.node.attr`::
 
   A node attribute to filter out nodes that are eligible as a gateway node in

+ 6 - 4
docs/reference/modules/remote-clusters.asciidoc

@@ -68,10 +68,12 @@ local and remote nodes.
 include::remote-clusters-shared.asciidoc[tag=remote-cluster-compatibility-matrix]
 ====
 
-* *role*: Dedicated master nodes are never selected as gateway nodes.
-* *attributes*: You can tag which nodes should be selected
-(see <<remote-clusters-settings,remote cluster settings>>), though such tagged nodes still have
-to satisfy the two above requirements.
+* *role*: By default, any non-<<master-node,master-eligible>> node can act as a
+gateway node. Dedicated master nodes are never selected as gateway nodes.
+
+* *attributes*: You can define the gateway nodes for a cluster by setting
+<<cluster-remote-node-attr,`cluster.remote.node.attr.gateway`>> to `true`.
+However, such nodes still have to satisfy the two above requirements.
 
 [[proxy-mode]]
 [discrete]

+ 35 - 34
docs/reference/search/search-your-data/search-across-clusters.asciidoc

@@ -5,8 +5,6 @@
 clusters. For example, you can use a {ccs} to filter and analyze log data stored
 on clusters in different data centers.
 
-IMPORTANT: {ccs-cap} requires <<remote-clusters,remote clusters>>.
-
 [discrete]
 [[ccs-supported-apis]]
 === Supported APIs
@@ -23,6 +21,37 @@ The following APIs support {ccs}:
 * experimental:[] <<sql-search-api,SQL search>>
 * experimental:[] <<search-vector-tile-api,Vector tile search>>
 
+[discrete]
+[[ccs-prereqs]]
+=== Prerequisites
+
+* {ccs-cap} requires remote clusters. To set up remote clusters on {ess},
+see link:{cloud}/ec-enable-ccs.html[configure remote clusters on {ess}]. If you
+run {es} on your own hardware, see <<remote-clusters>>.
++
+To ensure your remote cluster configuration supports {ccs}, see
+<<ccs-supported-configurations>>.
+
+* The local coordinating node must have the
+<<remote-node,`remote_cluster_client`>> node role.
+
+[[ccs-gateway-seed-nodes]]
+* If you use <<sniff-mode,sniff mode>>, the local coordinating node
+must be able to connect to seed and gateway nodes on the remote cluster.
++
+We recommend using gateway nodes capable of serving as coordinating nodes.
+The seed nodes can be a subset of these gateway nodes.
+
+[[ccs-proxy-mode]]
+* If you use <<proxy-mode,proxy mode>>, the local coordinating node must be able
+to connect to the configured `proxy_address`. The proxy at this address must be
+able to route connections to gateway and coordinating nodes on the remote
+cluster.
+
+* {ccs-cap} requires different security privileges on the local cluster and
+remote cluster. See <<remote-clusters-privileges-ccs>> and
+<<clusters-privileges-ccs-kibana>>.
+
 [discrete]
 [[ccs-example]]
 === {ccs-cap} examples
@@ -31,15 +60,8 @@ The following APIs support {ccs}:
 [[ccs-remote-cluster-setup]]
 ==== Remote cluster setup
 
-To perform a {ccs}, you must have at least one
-<<remote-clusters-connect,remote cluster configured>>.
-
-TIP: If you want to search across clusters in the cloud, you can
-link:{cloud}/ec-enable-ccs.html[configure remote clusters on {ess}]. Then, you
-can search across clusters and <<ccr-getting-started-tutorial,set up {ccr}>>.
-
 The following <<cluster-update-settings,cluster update settings>> API request
-adds three remote clusters:`cluster_one`, `cluster_two`, and `cluster_three`.
+adds three remote clusters: `cluster_one`, `cluster_two`, and `cluster_three`.
 
 [source,console]
 --------------------------------
@@ -75,6 +97,9 @@ PUT _cluster/settings
 [[ccs-search-remote-cluster]]
 ==== Search a single remote cluster
 
+In the search request, you specify data streams and indices on a remote cluster
+as `<remote_cluster_name>:<target>``.
+
 The following <<search-search,search>> API request searches the
 `my-index-000001` index on a single remote cluster, `cluster_one`.
 
@@ -288,30 +313,6 @@ PUT _cluster/settings
 If `cluster_two` is disconnected or unavailable during a {ccs}, {es} won't
 include matching documents from that cluster in the final results.
 
-[discrete]
-[[ccs-gateway-seed-nodes]]
-=== Selecting gateway and seed nodes in sniff mode
-
-For remote clusters using the <<sniff-mode,sniff connection>> mode, gateway and
-seed nodes need to be accessible from the local cluster via your network.
-
-By default, any non-<<master-node,master-eligible>> node can act as a
-gateway node. If wanted, you can define the gateway nodes for a cluster by
-setting `cluster.remote.node.attr.gateway` to `true`.
-
-For {ccs}, we recommend you use gateway nodes that are capable of serving as
-<<coordinating-node,coordinating nodes>> for search requests. If
-wanted, the seed nodes for a cluster can be a subset of these gateway nodes.
-
-[discrete]
-[[ccs-proxy-mode]]
-=== {ccs-cap} in proxy mode
-
-<<proxy-mode,Proxy mode>> remote cluster connections support {ccs}. All remote
-connections connect to the configured `proxy_address`. Any desired connection
-routing to gateway or <<coordinating-node,coordinating nodes>> must
-be implemented by the intermediate proxy at this configured address.
-
 [discrete]
 [[ccs-network-delays]]
 === How {ccs} handles network delays