elasticsearch/docs/reference/modules/cluster/remote-clusters-connect.asciidoc

[[remote-clusters-connect]]
=== Connect to remote clusters
Your local cluster uses the <<modules-network,transport interface>> to establish
communication with remote clusters. The coordinating nodes in the local cluster
establish <<long-lived-connections,long-lived>> TCP connections with specific
nodes in the remote cluster. {es} requires these connections to remain open,
even if the connections are idle for an extended period.

NOTE: You must have the `manage` cluster privilege to connect remote clusters.

To add a remote cluster from Stack Management in {kib}:

. Select *Remote Clusters* from the side navigation.
. Specify the {es} endpoint URL, or the IP address or host name of the remote
cluster followed by the transport port (defaults to `9300`). For example,
`cluster.es.eastus2.staging.azure.foundit.no:9400` or `192.168.1.1:9300`.

Alternatively, use the <<cluster-update-settings,cluster update settings API>>
to add a remote cluster. You can also use this API to 
<<configure-remote-clusters-dynamic,dynamically configure>> remote clusters for
_every_ node in the local cluster. To configure remote clusters on individual
nodes in the local cluster, define 
<<configure-remote-clusters-static,static settings>> in `elasticsearch.yml` for
each node.

After connecting remote clusters, 
<<remote-clusters-privileges,configure roles and users for remote clusters>>.

The following request adds a remote cluster with an alias of `cluster_one`. This
_cluster alias_ is a unique identifier that represents the connection to the 
remote cluster and is used to distinguish between local and remote indices.

[source,console]
----
PUT /_cluster/settings
{
  "persistent" : {
    "cluster" : {
      "remote" : {
        "cluster_one" : {    <1>
          "seeds" : [
            "127.0.0.1:9300" <2>
          ]
        }
      }
    }
  }
}
----
// TEST[setup:host]
// TEST[s/127.0.0.1:9300/\${transport_host}/]
<1> The cluster alias of this remote cluster is `cluster_one`.
<2> Specifies the hostname and transport port of a seed node in the remote
    cluster.

You can use the <<cluster-remote-info,remote cluster info API>> to verify that
the local cluster is successfully connected to the remote cluster:

[source,console]
----
GET /_remote/info
----
// TEST[continued]

The API response indicates that the local cluster is connected to the remote
cluster with the cluster alias `cluster_one`:

[source,console-result]
----
{
  "cluster_one" : {
    "seeds" : [
      "127.0.0.1:9300"
    ],
    "connected" : true,
    "num_nodes_connected" : 1,  <1>
    "max_connections_per_cluster" : 3,
    "initial_connect_timeout" : "30s",
    "skip_unavailable" : false, <2>
    "mode" : "sniff"
  }
}
----
// TESTRESPONSE[s/127.0.0.1:9300/$body.cluster_one.seeds.0/]
// TEST[s/"connected" : true/"connected" : $body.cluster_one.connected/]
// TEST[s/"num_nodes_connected" : 1/"num_nodes_connected" : $body.cluster_one.num_nodes_connected/]
<1> The number of nodes in the remote cluster the local cluster is
connected to.
<2> Indicates whether to skip the remote cluster if searched through {ccs} but
no nodes are available.

[[configure-remote-clusters-dynamic]]
==== Dynamically configure remote clusters
Use the <<cluster-update-settings,cluster update settings API>> to dynamically
configure remote settings on every node in the cluster. The following request
adds three remote clusters: `cluster_one`, `cluster_two`, and `cluster_three`.

The `seeds` parameter specifies the hostname and
<<transport-settings,transport port>> (default `9300`) of a seed node in the 
remote cluster.

The `mode` parameter determines the configured connection mode, which defaults
to <<sniff-mode,`sniff`>>. Because `cluster_one` doesn't specify a `mode`, it
uses the default. Both `cluster_two` and `cluster_three` explicitly use
different modes.

[source,console]
----
PUT _cluster/settings
{
  "persistent": {
    "cluster": {
      "remote": {
        "cluster_one": {
          "seeds": [
            "127.0.0.1:9300"
          ]
        },
        "cluster_two": {
          "mode": "sniff",
          "seeds": [
            "127.0.0.1:9301"
          ],
          "transport.compress": true,
          "skip_unavailable": true
        },
        "cluster_three": {
          "mode": "proxy",
          "proxy_address": "127.0.0.1:9302"
        }
      }
    }
  }
}
----
// TEST[setup:host]
// TEST[s/127.0.0.1:9300/\${transport_host}/]

You can dynamically update settings for a remote cluster after the initial configuration. The following request updates the
compression settings for `cluster_two`, and the compression and ping schedule
settings for `cluster_three`.

NOTE: When the compression or ping schedule settings change, all existing
node connections must close and re-open, which can cause in-flight requests to
fail.

[source,console]
----
PUT _cluster/settings
{
  "persistent": {
    "cluster": {
      "remote": {
        "cluster_two": {
          "transport.compress": false
        },
        "cluster_three": {
          "transport.compress": true,
          "transport.ping_schedule": "60s"
        }
      }
    }
  }
}
----
// TEST[continued]

You can delete a remote cluster from the cluster settings by passing `null`
values for each remote cluster setting. The following request removes
`cluster_two` from the cluster settings, leaving `cluster_one` and 
`cluster_three` intact:

[source,console]
----
PUT _cluster/settings
{
  "persistent": {
    "cluster": {
      "remote": {
        "cluster_two": {
          "mode": null,
          "seeds": null,
          "skip_unavailable": null,
          "transport.compress": null
        }
      }
    }
  }
}
----
// TEST[continued]

[[configure-remote-clusters-static]]
==== Statically configure remote clusters
If you specify settings in `elasticsearch.yml`, only the nodes with
those settings can connect to the remote cluster and serve remote cluster 
requests.

NOTE: Remote cluster settings that are specified using the 
<<cluster-update-settings,cluster update settings API>> take precedence over
settings that you specify in `elasticsearch.yml` for individual nodes.

In the following example, `cluster_one`, `cluster_two`, and `cluster_three` are 
arbitrary cluster aliases representing the connection to each cluster. These 
names are subsequently used to distinguish between local and remote indices.

[source,yaml]
----
cluster:
    remote:
        cluster_one:
            seeds: 127.0.0.1:9300
        cluster_two:
            mode: sniff
            seeds: 127.0.0.1:9301
            transport.compress: true      <1>
            skip_unavailable: true        <2>
        cluster_three:
            mode: proxy
            proxy_address: 127.0.0.1:9302 <3>

----
<1> Compression is explicitly enabled for requests to `cluster_two`.
<2> Disconnected remote clusters are optional for `cluster_two`.
<3> The address for the proxy endpoint used to connect to `cluster_three`.