﻿---
title: Connect Elastic Cloud Hosted deployments to an Elastic Cloud Enterprise environment
description: This section explains how to configure a deployment to connect remotely to clusters belonging to an Elastic Cloud Enterprise (ECE) environment. You can...
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5143/deploy-manage/remote-clusters/ec-remote-cluster-ece
products:
  - Elastic Cloud Hosted
applies_to:
  - Elastic Cloud Hosted: Generally available
  - Elastic Cloud Enterprise: Generally available
---

# Connect Elastic Cloud Hosted deployments to an Elastic Cloud Enterprise environment
This section explains how to configure a deployment to connect remotely to clusters belonging to an Elastic Cloud Enterprise (ECE) environment.
<admonition title="Note about terminology">
  In the case of remote clusters, the Elasticsearch cluster or deployment initiating the connection and requests is often referred to as the **local cluster**, while the Elasticsearch cluster or deployment receiving the requests is referred to as the **remote cluster**.
</admonition>

<note>
  If network security filters are applied to the remote cluster on ECE, the remote cluster administrator must configure an [IP filter](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5143/deploy-manage/security/ip-filtering-ece) to allow traffic from [Elastic Cloud IP addresses](/elastic/docs-content/pull/5143/deploy-manage/security/elastic-cloud-static-ips#ec-egress). For more information, refer to [Remote clusters and network security](/elastic/docs-content/pull/5143/deploy-manage/remote-clusters#network-security).
</note>


## Allow the remote connection

Before you start, consider the [security model](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5143/deploy-manage/remote-clusters/security-models) that you would prefer to use for authenticating remote connections between clusters, and follow the corresponding steps.
<definitions>
  <definition term="API key">
    For deployments based on Elastic Stack 8.14 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model uses a dedicated service endpoint, on port `9443` by default, and gives administrators fine-grained control over remote access. The API key is created on the remote cluster and defines the permissions available to all cross-cluster requests, while local user roles can further restrict, but not extend, those permissions.
  </definition>
  <definition term="TLS certificate (deprecated in Elastic Stack 9.0.0)">
    This model uses mutual TLS authentication over the Elasticsearch transport interface for cross-cluster operations. User authentication is performed on the local cluster and a user's role names are passed to the remote cluster for authorization. Because a superuser on the local cluster automatically gains full read access to the remote cluster, this model is only suitable for clusters within the same security domain.
  </definition>
</definitions>

<tab-set>
  <tab-item title="API key">
    Follow these steps to configure the [API key security model](/elastic/docs-content/pull/5143/deploy-manage/remote-clusters/security-models#api-key) for remote clusters. If you run into any issues, refer to [Troubleshooting](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5143/troubleshoot/elasticsearch/remote-clusters).

    ### Prerequisites and limitations

    - The local and remote deployments must be on Elastic Stack 8.14 or later.
    - Unlike the certificate-based security model, the API key model does not require mutual trust between clusters; only the local cluster is required to trust the remote cluster's certificate.


    ### Create a cross-cluster API key on the remote deployment

    1. On the remote cluster, use the [Elasticsearch API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key) or [Kibana](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5143/deploy-manage/api-keys/elasticsearch-api-keys) to create a cross-cluster API key. Configure it to include access to the indices you want to use for cross-cluster search or cross-cluster replication.
    2. Copy the encoded key (`encoded` in the response) to a safe location. It is required for the local cluster configuration.


    ### Configure the local deployment

    The API key created previously is needed by the local deployment to authenticate with the corresponding set of permissions to the remote deployment. To enable this, add the API key to the local deployment's keystore.The steps to follow depend on whether the Certificate Authority (CA) of the remote ECE environment’s proxy or load balancing infrastructure is public or private.
    <dropdown title="The CA is public">
      1. Log in to the [Elastic Cloud Console](https://cloud.elastic.co?page=docs&placement=docs-body).
      2. On the home page, find your hosted deployment and select **Manage** to access it directly. Or, select **Hosted deployments** to go to the **Hosted deployments** page to view all of your deployments.
         On the **Hosted deployments** page you can narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list.
      3. From the navigation menu, select **Security**.
      4. Locate **Remote Connections > Trust management > Connections using API keys** and select **Add API key**.
         1. Fill both fields.
         - For the **Remote cluster name**, enter the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores.
      - For the **Cross-cluster API key**, paste the encoded cross-cluster API key.
      2. Click **Add** to save the API key.
      5. Restart the local deployment to reload the new setting. To do that, go to the deployment's main page, locate the **Actions** menu, and select **Restart Elasticsearch**.
         <note>
         If the local deployment runs on version 8.14 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys.
         </note>

      If you need to update the remote connection with different permissions later, refer to [Change a cross-cluster API key used for a remote connection](/elastic/docs-content/pull/5143/deploy-manage/remote-clusters/ec-edit-remove-trusted-environment#edit-remove-trusted-environment-api-key).
    </dropdown>

    <dropdown title="The CA is private">
      Before configuring the local deployment, retrieve the CA certificate of the remote ECE proxy. To find this certificate:
      1. In the remote ECE environment, go to **Platform > Settings > TLS certificates**.
      2. Select **Show certificate chain** under **Proxy**.
      3. Click **Copy root certificate** and paste it into a new file. The root certificate is the last certificate shown in the chain.
         ![Certificate to copy from the chain](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5143/deploy-manage/images/cloud-remote-clusters-proxy-certificate.png)
      4. Save the file as `.crt`.

      You can now proceed to configure the local deployment. The CA file you saved will be used in one of the following steps.
      1. Log in to the [Elastic Cloud Console](https://cloud.elastic.co?page=docs&placement=docs-body).
      2. On the home page, find your hosted deployment and select **Manage** to access it directly. Or, select **Hosted deployments** to go to the **Hosted deployments** page to view all of your deployments.
         On the **Hosted deployments** page you can narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list.
      3. From the navigation menu, select **Security**.
      4. Select **Remote Connections > Add trusted environment** and choose **Elastic Cloud Enterprise**. Then click **Next**.
      5. Select **API keys** as authentication mechanism and click **Next**.
      6. When asked whether the Certificate Authority (CA) of the remote environment’s proxy or load-balancing infrastructure is public, select **No, it is private**.
      7. Add the API key:
         1. Fill both fields.
         - For the **Remote cluster name**, enter the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores.
      - For the **Cross-cluster API key**, paste the encoded cross-cluster API key.
      2. Click **Add** to save the API key.
      3. Repeat these steps for each API key you want to add. For example, if you want to use several clusters of the remote environment for CCR or CCS.
      8. Add the CA certificate of the remote environment.
      9. Provide a name for the trusted environment. That name will appear in the trust summary of your deployment's **Security** page.
      10. Select **Create trust** to complete the configuration.
      11. Restart the local deployment to reload the new settings. To do that, go to the deployment's main page, locate the **Actions** menu, and select **Restart Elasticsearch**.
         <note>
         If the local deployment runs on version 8.14 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys.
         </note>

      If you need to update the remote connection with different permissions later, refer to [Change a cross-cluster API key used for a remote connection](/elastic/docs-content/pull/5143/deploy-manage/remote-clusters/ec-edit-remove-trusted-environment#edit-remove-trusted-environment-api-key).
    </dropdown>
  </tab-item>

  <tab-item title="TLS certificate (deprecated)">
    ### Configuring trust with clusters of an Elastic Cloud Enterprise environmentA deployment can be configured to trust all or specific deployments in a remote ECE environment:

    1. Access the **Security** page of the deployment you want to use for cross-cluster operations.
    2. Select **Remote Connections > Add trusted environment** and choose **Elastic Cloud Enterprise**. Then click **Next**.
    3. Select **Certificates** as authentication mechanism and click **Next**.
    4. Enter the environment ID of the ECE environment. You can find it under Platform > Trust Management in your ECE administration UI.
    5. Upload the Certificate Authority of the ECE environment. You can download it from Platform > Trust Management in your ECE administration UI.
    6. Choose one of following options to configure the level of trust with the ECE environment:
       - **All deployments** - This deployment trusts all deployments in the ECE environment, including new deployments when they are created.
    - **Specific deployments** - Specify which of the existing deployments you want to trust in the ECE environment. 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**.
    7. Provide a name for the trusted environment. That name will appear in the trust summary of your deployment’s **Security** page.
    8. Select **Create trust** to complete the configuration.
    9. Configure the corresponding deployments of the ECE environment to [trust this deployment](/elastic/docs-content/pull/5143/deploy-manage/remote-clusters/ece-remote-cluster-ece-ess#ece-trust-ec). You will only be able to connect two deployments successfully when both of them trust each other.

    <note>
      The environment ID and cluster IDs must be entered fully and correctly. For security reasons, verification of the IDs is not possible. If cross-environment trust does not appear to be working, double-checking the IDs is a good place to start.
    </note>

    <dropdown title="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 ECE environment with environment ID `1053523734`, you need to update the trust settings with an additional direct trust relationship like this:
      ```json
      {
        "trust":{
          "accounts":[
            {
               "account_id":"ec38dd0aa45f4a69909ca5c81c27138a",
               "trust_all":true
            }
          ],
          "direct": [
            {
              "type" : "ECE",
              "name" : "My ECE environment",
              "scope_id" : "1053523734",
              "certificates" : [
                  {
                      "pem" : "-----BEGIN CERTIFICATE-----\nMIIDTzCCA...H0=\n-----END CERTIFICATE-----"
                  }
               ],
               "trust_all":false,
               "trust_allowlist":[
                  "cf659f7fe6164d9691b284ae36811be1"
               ]
             }
          ]
        }
      }
      ```
    </dropdown>
  </tab-item>
</tab-set>

You can now connect remotely to the trusted clusters.

## Connect to the remote cluster

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

### Using Kibana

To add a remote cluster in Kibana:
1. Go to the **Remote Clusters** management page in the navigation menu or use the [global search field](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5143/explore-analyze/find-and-organize/find-apps-and-objects).
2. Select **Add a remote cluster**.
3. In **Select connection type**, choose the authentication mechanism you prepared earlier (**API keys** or **Certificates**), and then click **Next**.
4. In **Add connection information**, fill in the following fields:
   - **Remote cluster name**: This *cluster alias* is a unique identifier that represents the connection to the remote cluster and is used to distinguish local and remote indices.
  When using API key authentication, this alias must match the **Remote cluster name** you configured when [adding the API key](#configure-local-cluster) in the Cloud UI.
- **Remote address**: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters** section.
  <note>
  If you’re using API keys as security model, change the port to `9443`.
  </note>
- **Configure advanced options** (optional): Expand this section if you need to customize additional settings.
  - **TLS server name**: Specify a value if the certificate presented by the remote cluster is signed for a different name than the remote address.
  This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. Copy the **Server name** from the **Remote cluster parameters** section.
- **Socket connections**: Define the number of connections to open with the remote cluster.
   For a full list of available client connection settings, refer to the [remote cluster settings reference](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/configuration-reference/remote-clusters#remote-cluster-proxy-settings).
5. Click **Next**.
6. In **Confirm setup**, click **Add remote cluster** (you have already established trust in a previous step).

<note>
  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](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5143/deploy-manage/deploy/cloud-enterprise/change-endpoint-urls).
</note>


### Using the Elasticsearch API

To add a remote cluster, use the [cluster update settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-put-settings). Configure the following fields:
- **Remote cluster alias**: When using API key authentication, the cluster alias must match the one you configured when [adding the API key](#configure-local-cluster) in the Cloud UI as **Remote cluster name**.
- **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. Copy the **Proxy address** from the **Remote cluster parameters** section.
  Using the API, this value can be obtained from the Elasticsearch resource info, concatenating the field `metadata.endpoint` and port `9400` using a semicolon.
  <note>
  If you’re using API keys as security model, change the port to `9443`.
  </note>
- **server_name**: This value can be found on the **Security** page of the Elastic Cloud Enterprise deployment you want to use as a remote. Copy the **Server name** from the **Remote cluster parameters** section.
  Using the API, this can be obtained from the Elasticsearch resource info field `metadata.endpoint`.

This example shows the API call to add or update a remote cluster. The alias `alias-for-my-remote-cluster` must match the remote cluster name used when adding the API key to the deployment:
```json
PUT /_cluster/settings
{
  "persistent": {
    "cluster": {
      "remote": {
        "alias-for-my-remote-cluster": {
          "mode":"proxy",
          "proxy_address": "<REMOTE_CLUSTER_ADDRESS>:9443",
          "server_name": "<REMOTE_CLUSTER_SERVER_NAME>"
        }
      }
    }
  }
}
```

For a full list of available client connection settings in proxy mode, refer to the [remote cluster settings reference](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/configuration-reference/remote-clusters#remote-cluster-proxy-settings).

## Configure roles and users

If you're using the API key–based security model for cross-cluster replication or cross-cluster search, you can define user roles with [remote indices privileges](/elastic/docs-content/pull/5143/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure#roles-remote-indices-priv) on the local cluster to further restrict the permissions granted by the API key. For more details, refer to [Configure roles and users](/elastic/docs-content/pull/5143/deploy-manage/remote-clusters/remote-clusters-api-key#remote-clusters-privileges-api-key).