﻿---
title: Connect Elastic Cloud Enterprise deployments to self-managed clusters
description: This section explains how to configure a deployment to connect remotely to self-managed clusters. You can now connect remotely to the trusted clusters...
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4880/deploy-manage/remote-clusters/ece-remote-cluster-self-managed
products:
  - Elastic Cloud Enterprise
applies_to:
  - Elastic Cloud Enterprise: Generally available in 4.0+
  - Self-managed Elastic deployments: Generally available in 9.0+
---

# Connect Elastic Cloud Enterprise deployments to self-managed clusters
This section explains how to configure a deployment to connect remotely to self-managed clusters.
<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>


## Allow the remote connection

Before you start, consider the [security model](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4880/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/4880/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/4880/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/4880/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 cluster. 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 environment’s Elasticsearch HTTPS server, proxy or, load balancing infrastructure is public or private.
    <dropdown title="The CA is public">
      1. [Log into the Cloud UI](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4880/deploy-manage/deploy/cloud-enterprise/log-into-cloud-ui).
      2. On the **Deployments** page, select your deployment.
         Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters.
      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/4880/deploy-manage/remote-clusters/ece-edit-remove-trusted-environment#edit-remove-trusted-environment-api-key).
    </dropdown>

    <dropdown title="The CA is private">
      1. [Log in to the Cloud UI](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4880/deploy-manage/deploy/cloud-enterprise/log-into-cloud-ui).
      2. On the **Deployments** page, select your deployment.
         Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters.
      3. From the navigation menu, select **Security**.
      4. Select **Remote Connections > Add trusted environment** and choose **Self-managed**. 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/4880/deploy-manage/remote-clusters/ece-edit-remove-trusted-environment#edit-remove-trusted-environment-api-key).
    </dropdown>
  </tab-item>

  <tab-item title="TLS certificate (deprecated)">
    ### Specify the deployments trusted to be used as remote clustersA deployment can be configured to trust all or specific deployments in any environment:

    1. From the **Security** menu, select **Remote Connections > Add trusted environment** and choose **Self-managed**, then click **Next**.
    2. Select **Certificates** as authentication mechanism and click **Next**.
    3. Upload the public certificate for the Certificate Authority of the self-managed environment (the one used to sign all the cluster certificates). The certificate needs to be in PEM format and should not contain the private key. If you only have the key in p12 format, then you can create the necessary file like this: `openssl pkcs12 -in elastic-stack-ca.p12 -out newfile.crt.pem -clcerts -nokeys`
    4. Select the clusters to trust. There are two options here depending on the subject name of the certificates presented by the nodes in your self managed cluster:
       - Following the Elastic Cloud pattern. In Elastic Cloud, the certificates of all Elasticsearch nodes follow this convention: `CN = {{node_id}}.node.{{cluster_id}}.cluster.{{scope_id}}`. If you follow the same convention in your self-managed environment, then choose this option and you will be able to select all or specific clusters to trust.
    - If your clusters don’t follow the previous convention for the certificates subject name of your nodes, you can still specify the node name of each of the nodes that should be trusted by this deployment. (Keep in mind that following this convention will simplify the management of this cluster since otherwise this configuration will need to be updated every time the topology of your self-managed cluster changes along with the trust restriction file. For this reason, it is recommended migrating your cluster certificates to follow the previous convention).
      <note>
      Trust management will not work properly in clusters without an `otherName` value specified, as is the case by default in an out-of-the-box [Elasticsearch installation](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4880/deploy-manage/deploy/self-managed/installing-elasticsearch). To have the Elasticsearch certutil generate new certificates with the `otherName` attribute, use the file input with the `cn` attribute as in the example below.
      </note>
    5. Provide a name for the trusted environment. That name will appear in the trust summary of your deployment’s **Security** page.
    6. Select **Create trust** to complete the configuration.
    7. Configure the self-managed cluster to trust this deployment, so that both deployments are configured to trust each other:
       - Download the Certificate Authority used to sign the certificates of your deployment nodes (it can be found in the Security page of your deployment)
    - Trust this CA either using the [setting](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/configuration-reference/security-settings) `xpack.security.transport.ssl.certificate_authorities` in [`elasticsearch.yml`](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4880/deploy-manage/stack-settings) or by [adding it to the trust store](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4880/deploy-manage/security/different-ca).
    8. Generate certificates with an `otherName` attribute using the Elasticsearch certutil. Create a file called `instances.yaml` with all the details of the nodes in your on-premise cluster like below. The `dns` and `ip` settings are optional, but `cn` is mandatory for use with the `trust_restrictions` path setting in the next step. Next, run `./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 -in instances.yaml` to create new certificates for all the nodes at once. You can then copy the resulting files into each node.
       ```yaml
       instances:
         - name: "node1"
           dns: ["<NODE1_FQDN>"]
           ip: ["192.0.2.1"]
           cn: ["node1.node.1234567abcd.cluster.myscope.account"]
         - name: "node2"
           dns: ["<NODE2_FQDN>"]
           ip: ["192.0.2.2"]
           cn: ["node2.node.1234567abcd.cluster.myscope.account"]
       ```
    9. Restrict the trusted clusters to allow only the ones which your self-managed cluster should trust.
       - All the clusters in your Elastic Cloud Enterprise environment are signed by the same certificate authority. Therefore, adding this CA would make the self-managed cluster trust all your clusters in your ECE environment. This should be limited using the setting `xpack.security.transport.ssl.trust_restrictions.path` in [`elasticsearch.yml`](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4880/deploy-manage/stack-settings), which points to a file that limits the certificates to trust based on their `otherName`-attribute.
    - For example, the following file would trust:
      ```yaml
        trust.subject_name:
        - *.node.aaaabbbbaaaabbbb.cluster.1053523734.account 
        - *.node.xxxxyyyyxxxxyyyy.cluster.1053523734.account 
        - *.node.*.cluster.83988631.account 
        - node*.<CLUSTER_FQDN> 
      ```

    <tip>
      Generate new node certificates for an entire cluster using the file input mode of the certutil.
    </tip>

    <dropdown title="Using the API">
      You can update a deployment using the appropriate trust settings for the Elasticsearch payload.In order to trust a cluster whose nodes present certificates with the subject names: "CN = node1.<CLUSTER_FQDN>", "CN = node2.<CLUSTER_FQDN>" and "CN = node3.<CLUSTER_FQDN>" in a self-managed environment, you could update the trust settings with an additional direct trust relationship like this:
      ```json
      {
        "trust":{
          "accounts":[
            {
               "account_id":"ec38dd0aa45f4a69909ca5c81c27138a",
               "trust_all":true
            }
          ],
          "direct": [
            {
              "type" : "generic",
              "name" : "My Self-managed environment",
              "additional_node_names" : ["node1.<CLUSTER_FQDN>", "node2.<CLUSTER_FQDN>", "node3.<CLUSTER_FQDN>",],
              "certificates" : [
                  {
                      "pem" : "-----BEGIN CERTIFICATE-----\nMIIDTzCCA...H0=\n-----END CERTIFICATE-----"
                  }
               ],
               "trust_all":false
             }
          ]
        }
      }
      ```
    </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.
<note>
  This configuration of remote clusters uses the [Proxy mode](/elastic/docs-content/pull/4880/deploy-manage/remote-clusters/remote-clusters-self-managed#proxy-mode) and requires the ECE allocators to be able to connect to the remote address endpoint.
</note>


### 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/4880/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 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).
- **Remote address**: Enter the endpoint of the remote cluster, including the hostname, FQDN, or IP address, and the port.
  Make sure you use the correct port for your authentication method:
  - **API keys**: Use the port configured in the remote cluster interface of the remote cluster (defaults to `9443`).
- **TLS Certificates**: Use the Elasticsearch transport port (defaults to `9300`).
  Starting with Kibana 9.2, this field also supports IPv6 addresses. When using an IPv6 address, enclose it in square brackets followed by the port number. For example: `[2001:db8::1]:9443`.
- **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.
- **Socket connections**: Define the number of connections to open with the remote cluster.
5. Click **Next**.
6. In **Confirm setup**, click **Add remote cluster** (you have already established trust in a previous step).


### 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).
- **mode**: `proxy`
- **proxy_address**: Enter the endpoint of the remote cluster, including the hostname, FQDN, or IP address, and the port. Both IPv4 and IPv6 addresses are supported.
  Make sure you use the correct port for your authentication method:
  - **API keys**: Use the port configured in the remote cluster interface of the remote cluster (defaults to `9443`).
- **TLS Certificates**: Use the Elasticsearch transport port (defaults to `9300`).
  When using an IPv6 address, enclose it in square brackets followed by the port number. For example: `[2001:db8::1]:9443`.
- **server_name**: Specify a value if the certificate presented by the remote cluster is signed for a different name than the proxy_address.

This is an example of the API call to add or update a remote cluster:
```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/4880/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/4880/deploy-manage/remote-clusters/remote-clusters-api-key#remote-clusters-privileges-api-key).