Docs
You are looking at preliminary documentation for a future release. Not what you want? See the current release documentation.
Elasticsearch Reference [master] » Secure a cluster » Cross-cluster search, clients, and integrations » Cross-cluster search and security
« Cross-cluster search, clients, and integrations HTTP/REST clients and security »

Cross-cluster search and securityedit

Cross-cluster search enables federated search across multiple clusters. When using cross cluster search with secured clusters, all clusters must have the Elasticsearch security features enabled.

The local cluster (the cluster used to initiate cross cluster search) must be allowed to connect to the remote clusters, which means that the CA used to sign the SSL/TLS key of the local cluster must be trusted by the remote clusters.

User authentication is performed on the local cluster and the user and user’s roles are passed to the remote clusters. A remote cluster checks the user’s roles against its local role definitions to determine which indices the user is allowed to access.

This feature was added as Beta in Elasticsearch v5.3 with further improvements made in 5.4 and 5.5. It requires gateway eligible nodes to be on v5.5 onwards.

To use cross cluster search with secured clusters:

  • Enable the Elasticsearch security features on every node in each connected cluster. For more information about the xpack.security.enabled setting, see Security settings.
  • Enable encryption globally. To encrypt communications, you must enable enable SSL/TLS on every node.

  • Enable a trust relationship between the cluster used for performing cross cluster search (the local cluster) and all remote clusters. This can be done either by:

    • Using the same certificate authority to generate certificates for all connected clusters, or
    • Adding the CA certificate from the local cluster as a trusted CA in each remote cluster (see Transport TLS/SSL settings).
  • On the local cluster, ensure that users are assigned to (at least) one role that exists on the remote clusters. On the remote clusters, use that role to define which indices the user may access. (See User authorization).

  • Configure the local cluster to connect to remote clusters as described in Configuring remote clusters. For example, the following configuration adds two remote clusters to the local cluster:

    PUT _cluster/settings
{
  "persistent": {
    "cluster": {
      "remote": {
        "one": {
          "seeds": [ "10.0.1.1:9300" ]
        },
        "two": {
          "seeds": [ "10.0.2.1:9300" ]
        }
      }
    }
  }
}

Example configuration of cross cluster searchedit

In the following example, we will configure the user alice to have permissions to search any index starting with logs- in cluster two from cluster one.

First, enable cluster one to perform cross cluster search on remote cluster two by running the following request as the superuser on cluster one:

PUT _cluster/settings
{
  "persistent": {
    "cluster.remote.two.seeds": [ "10.0.2.1:9300" ]
  }
}

Next, set up a role called cluster_two_logs on both cluster one and cluster two.

On cluster one, this role does not need any special privileges:

POST /_security/role/cluster_two_logs
{
}

On cluster two, this role allows the user to query local indices called logs- from a remote cluster:

POST /_security/role/cluster_two_logs
{
  "cluster": [],
  "indices": [
    {
      "names": [
        "logs-*"
      ],
      "privileges": [
        "read",
        "read_cross_cluster"
      ]
    }
  ]
}

Finally, create a user on cluster one and apply the cluster_two_logs role:

POST /_security/user/alice
{
  "password" : "somepassword",
  "roles" : [ "cluster_two_logs" ],
  "full_name" : "Alice",
  "email" : "alice@example.com",
  "enabled": true
}

With all of the above setup, the user alice is able to search indices in cluster two as follows:

GET two:logs-2017.04/_search
{
  "query": {
    "match_all": {}
  }
}

Cross-cluster search and Kibanaedit

When Kibana is used to search across multiple clusters, a two-step authorization process determines whether or not the user can access indices on a remote cluster:

  • First, the local cluster determines if the user is authorized to access remote clusters. (The local cluster is the cluster Kibana is connected to.)
  • If they are, the remote cluster then determines if the user has access to the specified indices.

To grant Kibana users access to remote clusters, assign them a local role with read privileges to indices on the remote clusters. You specify remote cluster indices as <remote_cluster_name>:<index_name>.

To enable users to actually read the remote indices, you must create a matching role on the remote clusters that grants the read_cross_cluster privilege and access to the appropriate indices.

For example, if Kibana is connected to the cluster where you’re actively indexing Logstash data (your local cluster) and you’re periodically offloading older time-based indices to an archive cluster (your remote cluster) and you want to enable Kibana users to search both clusters:

  1. On the local cluster, create a logstash_reader role that grants read and view_index_metadata privileges on the local logstash-* indices.

    If you configure the local cluster as another remote in Elasticsearch, the logstash_reader role on your local cluster also needs to grant the read_cross_cluster privilege.

  2. Assign your Kibana users a role that grants access to Kibana as well as your logstash_reader role.
  3. On the remote cluster, create a logstash_reader role that grants the read_cross_cluster privilege and read and view_index_metadata privileges for the logstash-* indices.
« Cross-cluster search, clients, and integrations HTTP/REST clients and security »