Access deployments of an Elasticsearch Service organization

edit

This section explains how to configure a deployment to connect remotely to clusters belonging to an Elasticsearch Service organization.

Allow the remote connection

edit

Before you start, consider the security model that you would prefer to use for authenticating remote connections between clusters, and follow the corresponding steps.

API key
[beta] This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features. For deployments based on Elastic Stack version 8.10 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model offers administrators of both the local and the remote deployment fine-grained access controls.
TLS certificate
This model uses mutual TLS authentication for cross-cluster operations. User authentication is performed on the local cluster and a user’s role names are passed to the remote cluster. A superuser on the local deployment gains total read access to the remote deployment, so it is only suitable for deployments that are in the same security domain.
Configuring trust with clusters in Elastic Cloud
edit

A deployment can be configured to trust all or specific deployments from an organization in Elastic Cloud:

  1. From the Security menu, select Remote Connections > Add trusted environment and select Elastic Cloud Organization.
  2. Enter the organization ID (which can be found near the organization name).
  3. Upload the Certificate Authorities of the deployments you want to trust. These can be downloaded from the Security page of each deployment (not only the current CA, but also future certificates in case they are expiring soon since they are periodically rotated). Deployments from the same region are signed by the same CA, so you will only need to upload one for each region.
  4. Choose one of following options to configure the level of trust with the Organization:

    • All deployments - This deployment trusts all deployments in the organization in the regions whose certificate authorities have been uploaded, including new deployments when they are created.
    • Specific deployments - Specify which of the existing deployments you want to trust from this organization. The full Elasticsearch cluster ID must be entered for each remote cluster. The Elasticsearch Cluster ID can be found in the deployment overview page under Applications.
  5. Configure the deployment in Elastic Cloud to trust this deployment, so that both deployments are configured to trust each other.

Note that the organization ID and cluster IDs must be entered fully and correctly. For security reasons, no verification of the IDs is possible. If cross-environment trust does not appear to be working, double-checking the IDs is a good place to start.

Using the API

You can update a deployment using the appropriate trust settings for the elasticsearch payload.

In order to trust a deployment with cluster id cf659f7fe6164d9691b284ae36811be1 (NOTE: use the Elasticsearch cluster ID, not the deployment ID) in an organization with organization ID 803289842, you need to update the trust settings with an additional direct trust relationship like this:

{
  "trust":{
    "accounts":[
      {
         "account_id":"ec38dd0aa45f4a69909ca5c81c27138a",
         "trust_all":true
      }
    ],
    "direct": [
      {
        "type" : "ESS",
        "name" : "My Organization",
        "scope_id" : "803289842",
        "certificates" : [
            {
                "pem" : "-----BEGIN CERTIFICATE-----\nMIIDTzCCA...H0=\n-----END CERTIFICATE-----"
            }
         ],
         "trust_all":false,
         "trust_allowlist":[
            "cf659f7fe6164d9691b284ae36811be1"
         ]
       }
    ]
  }
}

You can now connect remotely to the trusted clusters.

Connect to the remote cluster

edit

On the local cluster, add the remote cluster using Kibana or the Elasticsearch API.

Using Kibana
edit
  1. Open the Kibana main menu, and select Stack Management > Data > Remote Clusters > Add a remote cluster.
  2. Enable Manually enter proxy address and server name.
  3. Fill in the following fields:

    • Name: 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.
    • Proxy address: This value can be found on the Security page of the Elastic Cloud Enterprise deployment you want to use as a remote.

      If you’re using API keys as security model, change the port into 9443.

    • Server name: This value can be found on the Security page of the Elastic Cloud Enterprise deployment you want to use as a remote.

      Remote Cluster Parameters in Deployment

      If you’re having issues establishing the connection and the remote cluster is part of an Elastic Cloud Enterprise environment with a private certificate, make sure that the proxy address and server name match with the the certificate information. For more information, refer to Administering endpoints in Elastic Cloud Enterprise.

  4. Click Next.
  5. Click Add remote cluster (you have already established trust in a previous step).

This configuration of remote clusters uses the Proxy mode and it requires that the allocators can communicate via http with the proxies.

Using the Elasticsearch API
edit

To configure a deployment as a remote cluster, use the cluster update settings API. Configure the following fields:

  • mode: proxy
  • proxy_address: This value can be found on the Security page of the Elastic Cloud Enterprise deployment you want to use as a remote. Also, using the API, this value can be obtained from the Elasticsearch resource info, concatenating the field metadata.endpoint and port 9300 using a semicolon.

If you’re using API keys as security model, change the port into 9443.

  • server_name: This value can be found on the Security page of the Elastic Cloud Enterprise deployment you want to use as a remote. Also, using the API, this can be obtained from the Elasticsearch resource info field metadata.endpoint.

This is an example of the API call to _cluster/settings:

PUT /_cluster/settings
{
  "persistent": {
    "cluster": {
      "remote": {
        "alias-for-my-remote-cluster": {
          "mode":"proxy",
          "proxy_address": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9300",
          "server_name": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io"
        }
      }
    }
  }
}
Stack Version above 6.7.0 and below 7.6.0

This section only applies if you’re using TLS certificates as cross-cluster security model.

When the cluster to be configured as a remote is above 6.7.0 and below 7.6.0, the remote cluster must be configured using the sniff mode with the proxy field. For each remote cluster you need to pass the following fields:

  • Proxy: This value can be found on the Security page of the deployment you want to use as a remote under the name Proxy Address. Also, using the API, this can be obtained from the elasticsearch resource info, concatenating the fields metadata.endpoint and metadata.ports.transport_passthrough using a semicolon.
  • Seeds: This field is an array that must contain only one value, which is the server name that can be found on the Security page of the ECE deployment you want to use as a remote concatenated with :1. Also, using the API, this can be obtained from the Elasticsearch resource info, concatenating the fields metadata.endpoint and 1 with a semicolon.
  • Mode: sniff (or empty, since sniff is the default value)

This is an example of the API call to _cluster/settings:

{
  "persistent": {
    "cluster": {
      "remote": {
        "my-remote-cluster-1": {
          "seeds": [
            "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:1"
          ],
          "proxy": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400"
        }
      }
    }
  }
}
Using the Elastic Cloud Enterprise RESTful API
edit

This section only applies if you’re using TLS certificates as cross-cluster security model and when both clusters belong to the same ECE environment (for other scenarios, the Elasticsearch API should be used instead):

curl -k -H 'Content-Type: application/json' -X PUT -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters -d '
{
  "resources" : [
    {
      "deployment_id": "$DEPLOYMENT_ID_REMOTE",
      "elasticsearch_ref_id": "$REF_ID_REMOTE",
      "alias": "alias-your-remote",
      "skip_unavailable" : true
    }
  ]
}'
DEPLOYMENT_ID_REMOTE
The ID of your remote deployment, as shown in the Cloud UI or obtained through the API.
REF_ID_REMOTE
The unique ID of the Elasticsearch resources inside your remote deployment (you can obtain these values through the API).

Note the following when using the Elastic Cloud Enterprise RESTful API:

  1. A cluster alias must contain only letters, numbers, dashes (-), or underscores (_).
  2. To learn about skipping disconnected clusters, refer to the Elasticsearch documentation.
  3. When remote clusters are already configured for a deployment, the PUT request replaces the existing configuration with the new configuration passed. Passing an empty array of resources will remove all remote clusters.

The following API request retrieves the remote clusters configuration:

curl -k -X GET -H "Authorization: ApiKey $ECE_API_KEY" https://COORDINATOR_HOST:12443/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters

The response includes just the remote clusters from the same ECE environment. In order to obtain the whole list of remote clusters, use Kibana or the Elasticsearch API Elasticsearch API directly.

Configure roles and users

edit

To use a remote cluster for cross-cluster replication or cross-cluster search, you need to create user roles with remote indices privileges on the local cluster. Refer to Configure roles and users.