﻿---
title: Remote clusters on Elastic Cloud on Kubernetes
description: The remote clusters module in Elasticsearch enables you to establish uni-directional connections to a remote cluster. This functionality is used in cross-cluster...
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4241/deploy-manage/remote-clusters/eck-remote-clusters
products:
  - Elastic Cloud on Kubernetes
---

# Remote clusters on Elastic Cloud on Kubernetes
The [remote clusters module](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4241/deploy-manage/remote-clusters) in Elasticsearch enables you to establish uni-directional connections to a remote cluster. This functionality is used in cross-cluster replication and cross-cluster search.
When using remote cluster connections with ECK, the setup process depends on where the remote cluster is deployed.

## Connect to Elasticsearch clusters in the same ECK environment

<note>
  The remote clusters feature requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4241/deploy-manage/license/manage-your-license-in-eck) for more details about managing licenses.
</note>

To create a remote cluster connection to another Elasticsearch cluster deployed within the same Kubernetes cluster, specify the `remoteClusters` attribute in your Elasticsearch spec.

### Security models

Before you start, consider the [security model](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4241/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>


### Using the API key security model

To enable the API key security model you must first enable the remote cluster server on the remote Elasticsearch cluster:
```yaml
apiVersion: elasticsearch.k8s.elastic.co/v1
kind: Elasticsearch
metadata:
  name: cluster-two
  namespace: ns-two
spec:
  version: 8.16.1
  remoteClusterServer:
    enabled: true
  nodeSets:
    - name: default
      count: 3
```

<note>
  Enabling the remote cluster server triggers a restart of the Elasticsearch cluster.
</note>

Once the remote cluster server is enabled and started on the remote cluster you can configure the Elasticsearch reference on the local cluster to include the desired permissions for cross-cluster search, and cross-cluster replication.
Permissions have to be included under the `apiKey` field. The API model of the Elasticsearch resource is compatible with the [Elasticsearch Cross-Cluster API key API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key) model. Fine-grained permissions can therefore be configured in both the `search` and `replication` fields:
```yaml
apiVersion: elasticsearch.k8s.elastic.co/v1
kind: Elasticsearch
metadata:
  name: cluster-one
  namespace: ns-one
spec:
  nodeSets:
  - count: 3
    name: default
  remoteClusters:
  - name: cluster-two
    elasticsearchRef:
      name: cluster-two
      namespace: ns-two
    apiKey:
      access:
        search:
          names:
            - kibana_sample_data_ecommerce  
        replication:
          names:
            - kibana_sample_data_ecommerce  
  version: 8.16.1
```

You can find a complete example in the [recipes directory](https://github.com/elastic/cloud-on-k8s/tree/3.2/config/recipes/remoteclusters).

### Using the certificate security model

The following example describes how to configure `cluster-two` as a remote cluster in `cluster-one` using the certificate security model:
```yaml
apiVersion: elasticsearch.k8s.elastic.co/v1
kind: Elasticsearch
metadata:
  name: cluster-one
  namespace: ns-one
spec:
  nodeSets:
  - count: 3
    name: default
  remoteClusters:
  - name: cluster-two
    elasticsearchRef:
      name: cluster-two
      namespace: ns-two 
  version: 8.16.1
```


## Connect from an Elasticsearch cluster running outside the Kubernetes cluster

<note>
  While it is technically possible to configure remote cluster connections using older versions of Elasticsearch, this guide only covers the setup for Elasticsearch 7.6 and later. The setup process is significantly simplified in Elasticsearch 7.6 due to improved support for the indirection of Kubernetes services.
</note>

You can configure a remote cluster connection to an ECK-managed Elasticsearch cluster from another cluster running outside the Kubernetes cluster as follows:
1. Make sure that both clusters trust each other’s certificate authority.
2. Configure the remote cluster connection through the Elasticsearch REST API.

Consider the following example:
- `cluster-one` resides inside Kubernetes and is managed by ECK
- `cluster-two` is not hosted inside the same Kubernetes cluster as `cluster-one` and may not even be managed by ECK

To configure `cluster-one` as a remote cluster in `cluster-two`:

### Make sure both clusters trust each other’s certificate authority

The certificate authority (CA) used by ECK to issue certificates for the Elasticsearch transport layer is stored in a secret named `<cluster_name>-es-transport-certs-public`. Extract the certificate for `cluster-one` as follows:
```sh
kubectl get secret cluster-one-es-transport-certs-public \
-o go-template='{{index .data "ca.crt" | base64decode}}' > remote.ca.crt
```

You then need to configure the CA as one of the trusted CAs in `cluster-two`. If that cluster is hosted outside of Kubernetes, take the CA certificate that you have just extracted and add it to the list of CAs in [`xpack.security.transport.ssl.certificate_authorities`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/configuration-reference/security-settings#_pem_encoded_files_3).
<note>
  Beware of copying the source Secret as-is into a different namespace. Check [Common Problems: Owner References](/elastic/docs-content/pull/4241/troubleshoot/deployments/cloud-on-k8s/common-problems#k8s-common-problems-owner-refs) for more information.
</note>

<note>
  CA certificates are automatically rotated after one year by default. You can [configure](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/4241/deploy-manage/deploy/cloud-on-k8s/configure-eck) this period. Make sure to keep the copy of the certificates Secret up-to-date.
</note>

If `cluster-two` is also managed by an ECK instance, proceed as follows:
1. Create a config map with the CA certificate you just extracted:
   ```sh
   kubectl create configmap remote-certs --from-file=ca.crt=remote.ca.crt
   ```
2. Use this config map to configure `cluster-one`'s CA as a trusted CA in `cluster-two`:
   ```yaml
   apiVersion: elasticsearch.k8s.elastic.co/v1
   kind: Elasticsearch
   metadata:
     name: cluster-two
   spec:
     transport:
       tls:
         certificateAuthorities:
           configMapName: remote-certs
     nodeSets:
     - count: 3
       name: default
     version: 8.16.1
   ```
3. Repeat steps 1 and 2 to add the CA of `cluster-two` to `cluster-one` as well.


### Configure the remote cluster connection through the Elasticsearch REST API

Expose the transport layer of `cluster-one`.
```yaml
apiVersion: elasticsearch.k8s.elastic.co/v1
kind: Elasticsearch
metadata:
  name: cluster-one
spec:
  transport:
    service:
      spec:
        type: LoadBalancer 
```

Finally, configure `cluster-one` as a remote cluster in `cluster-two` using the Elasticsearch REST API:
```sh
PUT _cluster/settings
{
  "persistent": {
    "cluster": {
      "remote": {
        "cluster-one": {
          "mode": "proxy", 
          "proxy_address": "${LOADBALANCER_IP}:9300" 
        }
      }
    }
  }
}
```