From 8ed8f528269998c45a24883961b8afed61d3e1c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Tue, 25 Nov 2025 19:23:45 +0100 Subject: [PATCH 01/14] WIP rcs eck --- .../_snippets/eck_rcs_intro.md | 2 + .../eck-remote-clusters-from-external.md | 158 +++++++++++++ .../eck-remote-clusters-same-eck.md | 115 ++++++++++ .../eck-remote-clusters-to-external.md | 39 ++++ .../remote-clusters/eck-remote-clusters.md | 217 +----------------- deploy-manage/toc.yml | 4 + 6 files changed, 327 insertions(+), 208 deletions(-) create mode 100644 deploy-manage/remote-clusters/_snippets/eck_rcs_intro.md create mode 100644 deploy-manage/remote-clusters/eck-remote-clusters-from-external.md create mode 100644 deploy-manage/remote-clusters/eck-remote-clusters-same-eck.md create mode 100644 deploy-manage/remote-clusters/eck-remote-clusters-to-external.md diff --git a/deploy-manage/remote-clusters/_snippets/eck_rcs_intro.md b/deploy-manage/remote-clusters/_snippets/eck_rcs_intro.md new file mode 100644 index 0000000000..13020324e8 --- /dev/null +++ b/deploy-manage/remote-clusters/_snippets/eck_rcs_intro.md @@ -0,0 +1,2 @@ +The [remote clusters module](/deploy-manage/remote-clusters.md) in {{es}} enables you to establish uni-directional connections to a remote cluster. This functionality is used in cross-cluster replication and cross-cluster search. + diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md new file mode 100644 index 0000000000..1d48ce62ec --- /dev/null +++ b/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md @@ -0,0 +1,158 @@ +--- +navigation_title: From a self-managed cluster +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-remote-clusters.html +applies_to: + deployment: + eck: ga +products: + - id: cloud-kubernetes +--- + +# Connect a self-managed {{es}} cluster to an ECK-managed cluster + +(title update from the original "Connect from an Elasticsearch cluster running outside the Kubernetes cluster") --> This had ONLY TLS certs (deprecated) +(existing use case with TLS certs, API key missing) + +::::{include} _snippets/eck_rcs_intro.md +:::: + + +Intro, if the external cluster is managed by a different ECK, refer to "to external". +Intro: this doc assumes the local cluster is a self-managed cluster. + +from an external scope: only from self-managed to ECK, because: + +- From ECH/ECE to ECK already exist. +- From ECK to ECK (in to external). + + +### Using the API key security model + +If the local deployment is on ECH or ECE, refer to: +- EC doc +- ECE doc + +(TBD) - similar steps than EC/ECE to here. +1. Enable remote cluster server in the remote cluster + +2. Create API key in remote cluster + +3. Expose and obtain CA of the remote + +3. + +### Using the certificate security model +```{applies_to} +stack: deprecated 9.0 +``` + +::::{note} +While it is technically possible to configure remote cluster connections using older versions of {{es}}, this guide only covers the setup for {{es}} 7.6 and later. The setup process is significantly simplified in {{es}} 7.6 due to improved support for the indirection of Kubernetes services. +:::: + +You can configure a remote cluster connection to an ECK-managed {{es}} 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 {{es}} 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 [k8s_make_sure_both_clusters_trust_each_others_certificate_authority] + +The certificate authority (CA) used by ECK to issue certificates for the {{es}} transport layer is stored in a secret named `-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`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#_pem_encoded_files_3). + +::::{note} +Beware of copying the source Secret as-is into a different namespace. Check [Common Problems: Owner References](../../troubleshoot/deployments/cloud-on-k8s/common-problems.md#k8s-common-problems-owner-refs) for more information. +:::: + + +::::{note} +CA certificates are automatically rotated after one year by default. You can [configure](../deploy/cloud-on-k8s/configure-eck.md) this period. Make sure to keep the copy of the certificates Secret up-to-date. +:::: + + +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 {{es}} REST API [k8s_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 <1> +``` + +1. On cloud providers which support external load balancers, setting the type field to LoadBalancer provisions a load balancer for your Service. Alternatively, expose the service through one of the Kubernetes Ingress controllers that support TCP services. + + +Finally, configure `cluster-one` as a remote cluster in `cluster-two` using the {{es}} REST API: + +```sh +PUT _cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "cluster-one": { + "mode": "proxy", <1> + "proxy_address": "${LOADBALANCER_IP}:9300" <2> + } + } + } + } +} +``` + +1. Use "proxy" mode as `cluster-two` will be connecting to `cluster-one` through the Kubernetes service abstraction. +2. Replace `${LOADBALANCER_IP}` with the IP address assigned to the `LoadBalancer` configured in the previous code sample. If you have configured a DNS entry for the service, you can use the DNS name instead of the IP address as well. + + + + diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-same-eck.md b/deploy-manage/remote-clusters/eck-remote-clusters-same-eck.md new file mode 100644 index 0000000000..cd88346ceb --- /dev/null +++ b/deploy-manage/remote-clusters/eck-remote-clusters-same-eck.md @@ -0,0 +1,115 @@ +--- +navigation_title: To the same ECK environment +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-remote-clusters.html +applies_to: + deployment: + eck: ga +products: + - id: cloud-kubernetes +--- + +# Connect to {{es}} clusters in the same ECK environment [k8s-remote-clusters-connect-internal] + +::::{include} _snippets/eck_rcs_intro.md +:::: + + +::::{note} +The remote clusters feature requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../license/manage-your-license-in-eck.md) for more details about managing licenses. +:::: + + +To create a remote cluster connection to another {{es}} cluster deployed within the same Kubernetes cluster, specify the `remoteClusters` attribute in your {{es}} spec. + +### Security models [k8s_security_models] + +:::{include} _snippets/allow-connection-intro.md +::: + +### Using the API key security model [k8s_using_the_api_key_security_model] + +To enable the API key security model you must first enable the remote cluster server on the remote {{es}} 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 {{es}} cluster. +:::: + + +Once the remote cluster server is enabled and started on the remote cluster you can configure the {{es}} 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 {{es}} resource is compatible with the [{{es}} 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 <1> + replication: + names: + - kibana_sample_data_ecommerce <1> + version: 8.16.1 +``` + +1. This requires the sample data: [/explore-analyze/index.md#gs-get-data-into-kibana](/explore-analyze/index.md#gs-get-data-into-kibana) + + +You can find a complete example in the [recipes directory](https://github.com/elastic/cloud-on-k8s/tree/{{version.eck | M.M}}/config/recipes/remoteclusters). + + +### Using the certificate security model [k8s_using_the_certificate_security_model] +```{applies_to} +stack: deprecated 9.0 +``` + +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 <1> + version: 8.16.1 +``` + +1. The namespace declaration can be omitted if both clusters reside in the same namespace. diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md new file mode 100644 index 0000000000..d9d6f24146 --- /dev/null +++ b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md @@ -0,0 +1,39 @@ +--- +navigation_title: To an external cluster +mapped_pages: + - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-remote-clusters.html +applies_to: + deployment: + eck: ga +products: + - id: cloud-kubernetes +--- + +# Connect an ECK-managed cluster to an external {{es}} cluster +(Use case missing). + +::::{include} _snippets/eck_rcs_intro.md +:::: + + +Intro, the external / remote cluster in this case could be ECH/ECE/self-managed or even an ECK-managed cluster managed by a different operator. + +When the remote cluster is not handled by the same operator, there are certain things that the operator is not capable to do, so it requires some extra steps. + +(license considerations) + +This guide focuses on API key based authentication as the security model, as TLS cert based authentication is deprecated in favor of API. + +Steps: +1. Enable the remote cluster server on the remote (if it's ECH or ECE it's enabled by default) +2. Create an API key on the remote, get CA certificate. +3. Create the connection from the local ECK-managed Elasticsearch cluster + +(note: the orchestrator does NOT help in this process at all... or would it help?) + +process described here: https://github.com/elastic/cloud-on-k8s/issues/8502#issuecomment-2753674140 (for ECH) +(does it make sense to recreate N docs or try to create a single one?) +ECK to --> another ECK, self-managed, ECH, ECE. + + + diff --git a/deploy-manage/remote-clusters/eck-remote-clusters.md b/deploy-manage/remote-clusters/eck-remote-clusters.md index a85e645faf..587ce21072 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters.md @@ -11,220 +11,21 @@ products: # Remote clusters on {{eck}} [k8s-remote-clusters] -The [remote clusters module](/deploy-manage/remote-clusters.md) in {{es}} 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 {{es}} clusters in the same ECK environment [k8s-remote-clusters-connect-internal] - -::::{note} -The remote clusters feature requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../license/manage-your-license-in-eck.md) for more details about managing licenses. +::::{include} _snippets/eck_rcs_intro.md :::: +When using remote cluster connections with ECK, the setup process depends on where the remote cluster is deployed. -To create a remote cluster connection to another {{es}} cluster deployed within the same Kubernetes cluster, specify the `remoteClusters` attribute in your {{es}} spec. - -### Security models [k8s_security_models] - -:::{include} _snippets/allow-connection-intro.md -::: - -### Using the API key security model [k8s_using_the_api_key_security_model] - -To enable the API key security model you must first enable the remote cluster server on the remote {{es}} 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 {{es}} cluster. -:::: - - -Once the remote cluster server is enabled and started on the remote cluster you can configure the {{es}} 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 {{es}} resource is compatible with the [{{es}} 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 <1> - replication: - names: - - kibana_sample_data_ecommerce <1> - version: 8.16.1 -``` - -1. This requires the sample data: [/explore-analyze/index.md#gs-get-data-into-kibana](/explore-analyze/index.md#gs-get-data-into-kibana) - - -You can find a complete example in the [recipes directory](https://github.com/elastic/cloud-on-k8s/tree/{{version.eck | M.M}}/config/recipes/remoteclusters). - - -### Using the certificate security model [k8s_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 <1> - version: 8.16.1 -``` - -1. The namespace declaration can be omitted if both clusters reside in the same namespace. - - - - -## Connect from an {{es}} cluster running outside the Kubernetes cluster [k8s-remote-clusters-connect-external] - -::::{note} -While it is technically possible to configure remote cluster connections using older versions of {{es}}, this guide only covers the setup for {{es}} 7.6 and later. The setup process is significantly simplified in {{es}} 7.6 due to improved support for the indirection of Kubernetes services. -:::: - - -You can configure a remote cluster connection to an ECK-managed {{es}} 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 {{es}} 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 [k8s_make_sure_both_clusters_trust_each_others_certificate_authority] - -The certificate authority (CA) used by ECK to issue certificates for the {{es}} transport layer is stored in a secret named `-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`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#_pem_encoded_files_3). - -::::{note} -Beware of copying the source Secret as-is into a different namespace. Check [Common Problems: Owner References](../../troubleshoot/deployments/cloud-on-k8s/common-problems.md#k8s-common-problems-owner-refs) for more information. -:::: - - -::::{note} -CA certificates are automatically rotated after one year by default. You can [configure](../deploy/cloud-on-k8s/configure-eck.md) this period. Make sure to keep the copy of the certificates Secret up-to-date. +::::{include} _snippets/terminology.md :::: -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 {{es}} REST API [k8s_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 <1> -``` - -1. On cloud providers which support external load balancers, setting the type field to LoadBalancer provisions a load balancer for your Service. Alternatively, expose the service through one of the Kubernetes Ingress controllers that support TCP services. - - -Finally, configure `cluster-one` as a remote cluster in `cluster-two` using the {{es}} REST API: - -```sh -PUT _cluster/settings -{ - "persistent": { - "cluster": { - "remote": { - "cluster-one": { - "mode": "proxy", <1> - "proxy_address": "${LOADBALANCER_IP}:9300" <2> - } - } - } - } -} -``` - -1. Use "proxy" mode as `cluster-two` will be connecting to `cluster-one` through the Kubernetes service abstraction. -2. Replace `${LOADBALANCER_IP}` with the IP address assigned to the `LoadBalancer` configured in the previous code sample. If you have configured a DNS entry for the service, you can use the DNS name instead of the IP address as well. - +TBD, expand a bit the intro, explaining how the orchestrator helps in some use cases depending on the local and remote. +Links to use cases and configuration guides: +* Connect to {{es}} clusters in the same ECK environment +* Connect to external {{es}} clusters +* Connect from external {{es}} clusters +(+ prereqs? + security models? ) diff --git a/deploy-manage/toc.yml b/deploy-manage/toc.yml index 525288735f..322c65df2c 100644 --- a/deploy-manage/toc.yml +++ b/deploy-manage/toc.yml @@ -660,6 +660,10 @@ toc: - file: remote-clusters/remote-clusters-cert.md - file: remote-clusters/remote-clusters-migrate.md - file: remote-clusters/eck-remote-clusters.md + children: + - file: remote-clusters/eck-remote-clusters-same-eck.md + - file: remote-clusters/eck-remote-clusters-to-external.md + - file: remote-clusters/eck-remote-clusters-from-external.md - file: monitor.md children: - file: monitor/autoops.md From 03a02cca157dc5ffcb95536f491d485c094fef15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Wed, 26 Nov 2025 13:49:23 +0100 Subject: [PATCH 02/14] landing and intra-ECK almost completed --- .../_snippets/configure-roles-and-users.md | 2 +- .../_snippets/eck_rcs_intro.md | 3 +- .../eck-remote-clusters-from-external.md | 5 +- .../eck-remote-clusters-landing.md | 49 +++++++ .../eck-remote-clusters-same-eck.md | 115 ----------------- .../eck-remote-clusters-to-external.md | 5 +- .../remote-clusters/eck-remote-clusters.md | 122 ++++++++++++++++-- deploy-manage/toc.yml | 4 +- 8 files changed, 172 insertions(+), 133 deletions(-) create mode 100644 deploy-manage/remote-clusters/eck-remote-clusters-landing.md delete mode 100644 deploy-manage/remote-clusters/eck-remote-clusters-same-eck.md diff --git a/deploy-manage/remote-clusters/_snippets/configure-roles-and-users.md b/deploy-manage/remote-clusters/_snippets/configure-roles-and-users.md index 7a7110dba1..af8a515405 100644 --- a/deploy-manage/remote-clusters/_snippets/configure-roles-and-users.md +++ b/deploy-manage/remote-clusters/_snippets/configure-roles-and-users.md @@ -1,3 +1,3 @@ % this will need improvement in a future PR, as the text below is only valid for API key based security model -If you're using the API key based security model, to use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](/deploy-manage/remote-clusters/remote-clusters-api-key.md#remote-clusters-privileges-api-key). +If you're using the API key–based security model for {{ccr}} or {{ccs}}, you can define user roles with [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#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](/deploy-manage/remote-clusters/remote-clusters-api-key.md#remote-clusters-privileges-api-key). \ No newline at end of file diff --git a/deploy-manage/remote-clusters/_snippets/eck_rcs_intro.md b/deploy-manage/remote-clusters/_snippets/eck_rcs_intro.md index 13020324e8..afdbd3f603 100644 --- a/deploy-manage/remote-clusters/_snippets/eck_rcs_intro.md +++ b/deploy-manage/remote-clusters/_snippets/eck_rcs_intro.md @@ -1,2 +1 @@ -The [remote clusters module](/deploy-manage/remote-clusters.md) in {{es}} enables you to establish uni-directional connections to a remote cluster. This functionality is used in cross-cluster replication and cross-cluster search. - +The [remote clusters module](/deploy-manage/remote-clusters.md) in {{es}} enables you to establish uni-directional connections to a remote cluster. This functionality is used in cross-cluster replication (CCR) and cross-cluster search (CCS). diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md index 1d48ce62ec..4d1f5f3f7d 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md @@ -1,7 +1,5 @@ --- navigation_title: From a self-managed cluster -mapped_pages: - - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-remote-clusters.html applies_to: deployment: eck: ga @@ -11,6 +9,8 @@ products: # Connect a self-managed {{es}} cluster to an ECK-managed cluster +This guide explains how to configure remote cluster connections from an external {{es}} cluster to a cluster managed by ECK. + (title update from the original "Connect from an Elasticsearch cluster running outside the Kubernetes cluster") --> This had ONLY TLS certs (deprecated) (existing use case with TLS certs, API key missing) @@ -18,6 +18,7 @@ products: :::: +(note and links to other possible use cases and landing page) Intro, if the external cluster is managed by a different ECK, refer to "to external". Intro: this doc assumes the local cluster is a self-managed cluster. diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-landing.md b/deploy-manage/remote-clusters/eck-remote-clusters-landing.md new file mode 100644 index 0000000000..b58a1afd1e --- /dev/null +++ b/deploy-manage/remote-clusters/eck-remote-clusters-landing.md @@ -0,0 +1,49 @@ +--- +navigation_title: On Elastic Cloud on Kubernetes +applies_to: + deployment: + eck: ga +products: + - id: cloud-kubernetes +--- + +# Remote clusters on {{eck}} [k8s-remote-clusters] + +::::{include} _snippets/eck_rcs_intro.md +:::: + +::::{include} _snippets/terminology.md +:::: + +When using remote cluster connections with ECK, the setup process varies depending on how both the local and remote clusters are deployed: + +* When both clusters are managed by the same operator, ECK can automate certificate and API-key management, connection configuration, and reconciliation. +* When external clusters are involved, ECK provides limited automation, and additional manual configuration is required on both the local and remote clusters. + +## Prerequisites + +To use CCS or CCR, your {{es}} clusters must meet the following criteria: + +* The local and remote clusters must run on compatible versions of {{es}}. Review the version compatibility table. + + :::{include} _snippets/remote-cluster-certificate-compatibility.md + ::: + +* Network connectivity between the clusters. Review the [connection modes](./remote-cluster-connection-modes.md) and the [security models](./security-models.md) to understand the connectivity requirements for your specific setup. Remote cluster connections can operate through Kubernetes services, load balancers, reverse proxies, or other intermediaries, as long as the local cluster can reach the remote cluster’s endpoint. + +* The remote clusters feature on ECK requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../license/manage-your-license-in-eck.md) for more details about managing licenses. + +## Set up remote clusters with {{eck}} [eck-rcs-setup] + +Use one of the following guides depending on how the local and remote clusters are deployed. + +Connect from ECK-managed clusters: + + - [Connect to {{es}} clusters in the same ECK environment](./eck-remote-clusters-same-eck.md) + - [Connect to external {{es}} clusters or deployments](./eck-remote-clusters-to-external.md) + +Connect to ECK-managed clusters from external clusters: + + - [](./ec-enable-ccs-for-eck.md) + - [](./ece-enable-ccs-for-eck.md) + - [Connect self-managed {{es}} clusters to ECK](./eck-remote-clusters-from-external.md) diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-same-eck.md b/deploy-manage/remote-clusters/eck-remote-clusters-same-eck.md deleted file mode 100644 index cd88346ceb..0000000000 --- a/deploy-manage/remote-clusters/eck-remote-clusters-same-eck.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -navigation_title: To the same ECK environment -mapped_pages: - - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-remote-clusters.html -applies_to: - deployment: - eck: ga -products: - - id: cloud-kubernetes ---- - -# Connect to {{es}} clusters in the same ECK environment [k8s-remote-clusters-connect-internal] - -::::{include} _snippets/eck_rcs_intro.md -:::: - - -::::{note} -The remote clusters feature requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../license/manage-your-license-in-eck.md) for more details about managing licenses. -:::: - - -To create a remote cluster connection to another {{es}} cluster deployed within the same Kubernetes cluster, specify the `remoteClusters` attribute in your {{es}} spec. - -### Security models [k8s_security_models] - -:::{include} _snippets/allow-connection-intro.md -::: - -### Using the API key security model [k8s_using_the_api_key_security_model] - -To enable the API key security model you must first enable the remote cluster server on the remote {{es}} 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 {{es}} cluster. -:::: - - -Once the remote cluster server is enabled and started on the remote cluster you can configure the {{es}} 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 {{es}} resource is compatible with the [{{es}} 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 <1> - replication: - names: - - kibana_sample_data_ecommerce <1> - version: 8.16.1 -``` - -1. This requires the sample data: [/explore-analyze/index.md#gs-get-data-into-kibana](/explore-analyze/index.md#gs-get-data-into-kibana) - - -You can find a complete example in the [recipes directory](https://github.com/elastic/cloud-on-k8s/tree/{{version.eck | M.M}}/config/recipes/remoteclusters). - - -### Using the certificate security model [k8s_using_the_certificate_security_model] -```{applies_to} -stack: deprecated 9.0 -``` - -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 <1> - version: 8.16.1 -``` - -1. The namespace declaration can be omitted if both clusters reside in the same namespace. diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md index d9d6f24146..86f904f41e 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md @@ -1,7 +1,5 @@ --- navigation_title: To an external cluster -mapped_pages: - - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-remote-clusters.html applies_to: deployment: eck: ga @@ -12,10 +10,13 @@ products: # Connect an ECK-managed cluster to an external {{es}} cluster (Use case missing). +This guide explains how to configure remote clusters when your ECK-managed cluster connects to a self-managed cluster, an ECE/ECH deployment, or a cluster managed by another ECK operator. + ::::{include} _snippets/eck_rcs_intro.md :::: + Intro, the external / remote cluster in this case could be ECH/ECE/self-managed or even an ECK-managed cluster managed by a different operator. When the remote cluster is not handled by the same operator, there are certain things that the operator is not capable to do, so it requires some extra steps. diff --git a/deploy-manage/remote-clusters/eck-remote-clusters.md b/deploy-manage/remote-clusters/eck-remote-clusters.md index 587ce21072..23a3946c36 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters.md @@ -1,5 +1,5 @@ --- -navigation_title: On Elastic Cloud on Kubernetes +navigation_title: To the same ECK environment mapped_pages: - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-remote-clusters.html applies_to: @@ -9,23 +9,127 @@ products: - id: cloud-kubernetes --- -# Remote clusters on {{eck}} [k8s-remote-clusters] +# Connect to {{es}} clusters in the same ECK environment [k8s-remote-clusters-connect-internal] ::::{include} _snippets/eck_rcs_intro.md :::: -When using remote cluster connections with ECK, the setup process depends on where the remote cluster is deployed. +This guide explains how to configure remote clusters when both the local and remote clusters are managed by the same ECK operator. For other remote cluster scenarios with ECK, refer to [Remote clusters on ECK](./eck-remote-clusters-landing.md). + +::::{note} +The remote clusters feature requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../license/manage-your-license-in-eck.md) for more details about managing licenses. +:::: ::::{include} _snippets/terminology.md :::: +To create a remote cluster connection to another {{es}} cluster deployed within the same Kubernetes cluster, specify the `remoteClusters` attribute in your {{es}} spec. + +## Security models [k8s_security_models] + +:::{include} _snippets/allow-connection-intro.md +::: + + +## Setup [k8s_using_the_api_key_security_model] + +Based on the selected security model, use one of the following setup procedures. + +:::::::{tab-set} + +::::::{tab-item} API key + +### Enable the remote cluster server interface + +To enable the API key security model, you must first enable the remote cluster server on the remote {{es}} cluster by setting `spec.remoteClusterServer.enabled: true`: + +```yaml subs=true +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: cluster-two + namespace: ns-two +spec: + version: {{version.stack}} + remoteClusterServer: + enabled: true + nodeSets: + - name: default + count: 3 +``` + +::::{note} +Enabling the remote cluster server triggers a restart of the {{es}} cluster. +:::: + +### Add the remote cluster on the local cluster + +Once the remote cluster server is enabled and running on the remote cluster, you can configure the {{es}} reference on the local cluster and 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 {{es}} resource is compatible with the [{{es}} 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 subs=true +apiVersion: elasticsearch.k8s.elastic.co/v1 +kind: Elasticsearch +metadata: + name: cluster-one + namespace: ns-one +spec: + version: {{version.stack}} + remoteClusters: + - name: cluster-two + elasticsearchRef: + name: cluster-two <1> + namespace: ns-two <2> + apiKey: + access: + search: + names: + - kibana_sample_data_ecommerce <3> + replication: + names: + - kibana_sample_data_ecommerce <3> + nodeSets: + - count: 3 + name: default +``` +1. The name and namespace of the remote {{es}} cluster you are connecting to. +2. The namespace declaration can be omitted if both clusters reside in the same namespace. +3. This example requires the [{{kib}} sample data](/explore-analyze/index.md#gs-get-data-into-kibana). + + +You can find a complete example in the [recipes directory](https://github.com/elastic/cloud-on-k8s/tree/{{version.eck | M.M}}/config/recipes/remoteclusters). + +:::::: + +::::::{tab-item} TLS certificate (deprecated) +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 <1> + namespace: ns-two <2> + version: 8.16.1 +``` +1. The name and namespace of the remote {{es}} cluster you are connecting to. +2. The namespace declaration can be omitted if both clusters reside in the same namespace. -TBD, expand a bit the intro, explaining how the orchestrator helps in some use cases depending on the local and remote. +:::::: +::::::: -Links to use cases and configuration guides: -* Connect to {{es}} clusters in the same ECK environment -* Connect to external {{es}} clusters -* Connect from external {{es}} clusters +## Configure roles and users -(+ prereqs? + security models? ) +:::{include} _snippets/configure-roles-and-users.md +::: \ No newline at end of file diff --git a/deploy-manage/toc.yml b/deploy-manage/toc.yml index 322c65df2c..c6ebb55843 100644 --- a/deploy-manage/toc.yml +++ b/deploy-manage/toc.yml @@ -659,9 +659,9 @@ toc: - file: remote-clusters/remote-clusters-api-key.md - file: remote-clusters/remote-clusters-cert.md - file: remote-clusters/remote-clusters-migrate.md - - file: remote-clusters/eck-remote-clusters.md + - file: remote-clusters/eck-remote-clusters-landing.md children: - - file: remote-clusters/eck-remote-clusters-same-eck.md + - file: remote-clusters/eck-remote-clusters.md - file: remote-clusters/eck-remote-clusters-to-external.md - file: remote-clusters/eck-remote-clusters-from-external.md - file: monitor.md From a6cdda190b14f4b86aea81c4f20c2fff57b6cf8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Thu, 27 Nov 2025 16:32:25 +0100 Subject: [PATCH 03/14] refine remote cluster connection modes --- deploy-manage/remote-clusters/connection-modes.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/deploy-manage/remote-clusters/connection-modes.md b/deploy-manage/remote-clusters/connection-modes.md index 3cb6530a8c..982602a20c 100644 --- a/deploy-manage/remote-clusters/connection-modes.md +++ b/deploy-manage/remote-clusters/connection-modes.md @@ -19,9 +19,8 @@ Connection modes work independently of [security models](./security-models.md). The choice between proxy and sniff mode depends on your network architecture and deployment type. -- **Self-managed clusters:** If direct connections on the publish addresses between {{es}} nodes in both clusters are possible, you can use sniff mode. If direct connectivity is difficult to implement—for example, when clusters are separated by NAT, firewalls, or containerized environments—you can place a reverse proxy or load balancer in front of the remote cluster and use proxy mode instead. - -- **Managed environments ({{ece}}, {{ech}}, {{eck}}):** Direct node-to-node connectivity is generally not feasible, so these deployments always rely on the proxy connection mode. +- **Self-managed clusters:** If the local cluster can reach the publish addresses of the remote cluster’s nodes, you can use sniff mode. If direct connectivity is difficult to implement—for example, when clusters are separated by NAT, firewalls, or in containerized environments—you can place a reverse proxy or load balancer in front of the remote cluster and use proxy mode instead. +- **Managed environments ({{ece}}, {{ech}}, {{eck}}):** Because node publish addresses are not exposed externally in these platforms, they usually rely on the proxy connection mode when used as remote clusters. The following sections describe each method in more detail. From b9116713c5929d3ce4438f74f99d61752da58047 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 1 Dec 2025 14:23:15 +0100 Subject: [PATCH 04/14] major changes WIP --- .../_snippets/apikeys-create-key.md | 4 +- .../_snippets/apikeys-local-config-intro.md | 2 +- .../_snippets/eck_apikey_secret.md | 15 + .../_snippets/eck_rcs_enable.md | 2 +- .../_snippets/self_rcs_enable.md | 60 +++ .../remote-clusters/ec-enable-ccs-for-eck.md | 2 + .../remote-clusters/ec-remote-cluster-ece.md | 2 + .../ec-remote-cluster-other-ess.md | 2 + .../ec-remote-cluster-same-ess.md | 2 + .../ec-remote-cluster-self-managed.md | 2 + .../remote-clusters/ece-enable-ccs-for-eck.md | 2 + .../ece-remote-cluster-ece-ess.md | 2 + .../ece-remote-cluster-other-ece.md | 2 + .../ece-remote-cluster-same-ece.md | 2 + .../ece-remote-cluster-self-managed.md | 2 + .../eck-remote-clusters-from-external.md | 132 +++++-- .../eck-remote-clusters-landing.md | 4 +- .../eck-remote-clusters-to-external.md | 348 +++++++++++++++++- .../remote-clusters/eck-remote-clusters.md | 38 +- .../remote-clusters-api-key.md | 66 +--- 20 files changed, 556 insertions(+), 135 deletions(-) create mode 100644 deploy-manage/remote-clusters/_snippets/eck_apikey_secret.md create mode 100644 deploy-manage/remote-clusters/_snippets/self_rcs_enable.md diff --git a/deploy-manage/remote-clusters/_snippets/apikeys-create-key.md b/deploy-manage/remote-clusters/_snippets/apikeys-create-key.md index 6161f0073b..28348c8743 100644 --- a/deploy-manage/remote-clusters/_snippets/apikeys-create-key.md +++ b/deploy-manage/remote-clusters/_snippets/apikeys-create-key.md @@ -1,2 +1,2 @@ -* On the deployment you will use as remote, use the [{{es}} API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key) or [{{kib}}](/deploy-manage/api-keys/elasticsearch-api-keys.md) to create a cross-cluster API key. Configure it with access to the indices you want to use for {{ccs}} or {{ccr}}. -* Copy the encoded key (`encoded` in the response) to a safe location. You will need it in the next step. +1. On the remote cluster, use the [{{es}} API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key) or [{{kib}}](/deploy-manage/api-keys/elasticsearch-api-keys.md) to create a cross-cluster API key. Configure it to include access to the indices you want to use for {{ccs}} or {{ccr}}. +2. Copy the encoded key (`encoded` in the response) to a safe location. It is required for the local cluster configuration. diff --git a/deploy-manage/remote-clusters/_snippets/apikeys-local-config-intro.md b/deploy-manage/remote-clusters/_snippets/apikeys-local-config-intro.md index 5611e1ee12..5c4e65c425 100644 --- a/deploy-manage/remote-clusters/_snippets/apikeys-local-config-intro.md +++ b/deploy-manage/remote-clusters/_snippets/apikeys-local-config-intro.md @@ -1 +1 @@ -The API key created previously will be used by the local deployment to authenticate with the corresponding set of permissions to the remote deployment. For that, you need to add the API key to the local deployment's keystore. +The API key created previously is needed by the local {{local_type_generic}} to authenticate with the corresponding set of permissions to the remote {{remote_type_generic}}. To enable this, add the API key to the local {{local_type_generic}}'s keystore. \ No newline at end of file diff --git a/deploy-manage/remote-clusters/_snippets/eck_apikey_secret.md b/deploy-manage/remote-clusters/_snippets/eck_apikey_secret.md new file mode 100644 index 0000000000..932ddf4384 --- /dev/null +++ b/deploy-manage/remote-clusters/_snippets/eck_apikey_secret.md @@ -0,0 +1,15 @@ +The following command creates a secret with the API key encoded value obtained in the previous step: + +```sh +cat <.credentials: <1> +EOF +``` +1. For the ``, enter the alias of your choice. This alias is used when connecting to the remote cluster. It must be lowercase and only contain letters, numbers, dashes, and underscores. + diff --git a/deploy-manage/remote-clusters/_snippets/eck_rcs_enable.md b/deploy-manage/remote-clusters/_snippets/eck_rcs_enable.md index d92280a68d..0cfea48193 100644 --- a/deploy-manage/remote-clusters/_snippets/eck_rcs_enable.md +++ b/deploy-manage/remote-clusters/_snippets/eck_rcs_enable.md @@ -1,4 +1,4 @@ -By default, the remote cluster server interface is deactivated on ECK-managed clusters. To use the API key–based security model for cross-cluster connections, you must first enable it on the remote {{es}} cluster: +By default, the remote cluster server interface is deactivated on ECK-managed clusters. To use the API key–based security model for cross-cluster connections, you must first enable it on the remote {{es}} cluster by setting `spec.remoteClusterServer.enabled: true`: ```yaml subs=true apiVersion: elasticsearch.k8s.elastic.co/v1 diff --git a/deploy-manage/remote-clusters/_snippets/self_rcs_enable.md b/deploy-manage/remote-clusters/_snippets/self_rcs_enable.md new file mode 100644 index 0000000000..15361ef43c --- /dev/null +++ b/deploy-manage/remote-clusters/_snippets/self_rcs_enable.md @@ -0,0 +1,60 @@ +1. Enable the remote cluster server on every node of the remote cluster. In [`elasticsearch.yml`](/deploy-manage/stack-settings.md): + + 1. Set [`remote_cluster_server.enabled`](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#remote-cluster-network-settings) to `true`. + 2. Configure the bind and publish address for remote cluster server traffic, for example using [`remote_cluster.host`](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#remote-cluster-network-settings). Without configuring the address, remote cluster traffic may be bound to the local interface, and remote clusters running on other machines can't connect. + 3. Optionally, configure the remote server port using [`remote_cluster.port`](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#remote_cluster.port) (defaults to `9443`). + +2. Next, generate a certificate authority (CA) and a server certificate/key pair. On one of the nodes of the remote cluster, from the directory where {{es}} has been installed: + + 1. Create a CA, if you don't have a CA already: + + ```sh + ./bin/elasticsearch-certutil ca --pem --out=cross-cluster-ca.zip --pass CA_PASSWORD + ``` + + Replace `CA_PASSWORD` with the password you want to use for the CA. You can remove the `--pass` option and its argument if you are not deploying to a production environment. + + 2. Unzip the generated `cross-cluster-ca.zip` file. This compressed file contains the following content: + + ```txt + /ca + |_ ca.crt + |_ ca.key + ``` + + 3. Generate a certificate and private key pair for the nodes in the remote cluster: + + ```sh + ./bin/elasticsearch-certutil cert --out=cross-cluster.p12 --pass=CERT_PASSWORD --ca-cert=ca/ca.crt --ca-key=ca/ca.key --ca-pass=CA_PASSWORD --dns= --ip=192.0.2.1 + ``` + + * Replace `CA_PASSWORD` with the CA password from the previous step. + * Replace `CERT_PASSWORD` with the password you want to use for the generated private key. + * Use the `--dns` option to specify the relevant DNS name for the certificate. You can specify it multiple times for multiple DNS. + * Use the `--ip` option to specify the relevant IP address for the certificate. You can specify it multiple times for multiple IP addresses. + + 4. If the remote cluster has multiple nodes, you can either: + + * create a single wildcard certificate for all nodes; + * or, create separate certificates for each node either manually or in batch with the [silent mode](elasticsearch://reference/elasticsearch/command-line-tools/certutil.md#certutil-silent). + +3. On every node of the remote cluster: + + 1. Copy the `cross-cluster.p12` file from the earlier step to the `config` directory. If you didn't create a wildcard certificate, make sure you copy the correct node-specific p12 file. + 2. Add following configuration to [`elasticsearch.yml`](/deploy-manage/stack-settings.md): + + ```yaml + xpack.security.remote_cluster_server.ssl.enabled: true + xpack.security.remote_cluster_server.ssl.keystore.path: cross-cluster.p12 + ``` + + 3. Add the SSL keystore password to the {{es}} keystore: + + ```sh + ./bin/elasticsearch-keystore add xpack.security.remote_cluster_server.ssl.keystore.secure_password + ``` + + When prompted, enter the `CERT_PASSWORD` from the earlier step. + +4. Restart the remote cluster. + diff --git a/deploy-manage/remote-clusters/ec-enable-ccs-for-eck.md b/deploy-manage/remote-clusters/ec-enable-ccs-for-eck.md index 55e2d4efbb..265f27f6cd 100644 --- a/deploy-manage/remote-clusters/ec-enable-ccs-for-eck.md +++ b/deploy-manage/remote-clusters/ec-enable-ccs-for-eck.md @@ -9,6 +9,8 @@ applies_to: products: - id: cloud-hosted sub: + local_type_generic: deployment + remote_type_generic: cluster remote_type: Self-managed --- diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-ece.md b/deploy-manage/remote-clusters/ec-remote-cluster-ece.md index b80cffea85..f35731f5ce 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-ece.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-ece.md @@ -9,6 +9,8 @@ applies_to: products: - id: cloud-hosted sub: + local_type_generic: deployment + remote_type_generic: deployment remote_type: Elastic Cloud Enterprise --- diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md b/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md index 50109a5f5f..6fae02ea24 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md @@ -8,6 +8,8 @@ applies_to: products: - id: cloud-hosted sub: + local_type_generic: deployment + remote_type_generic: deployment remote_type: Elastic Cloud Hosted --- diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md b/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md index 0675f7318e..101845c9a7 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md @@ -8,6 +8,8 @@ applies_to: products: - id: cloud-hosted sub: + local_type_generic: deployment + remote_type_generic: deployment remote_type: Elastic Cloud Hosted --- diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md b/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md index a86322a079..f8a5d5b32a 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md @@ -9,6 +9,8 @@ applies_to: products: - id: cloud-hosted sub: + local_type_generic: deployment + remote_type_generic: cluster remote_type: Self-managed --- diff --git a/deploy-manage/remote-clusters/ece-enable-ccs-for-eck.md b/deploy-manage/remote-clusters/ece-enable-ccs-for-eck.md index c94416be73..cec4a92519 100644 --- a/deploy-manage/remote-clusters/ece-enable-ccs-for-eck.md +++ b/deploy-manage/remote-clusters/ece-enable-ccs-for-eck.md @@ -9,6 +9,8 @@ applies_to: products: - id: cloud-enterprise sub: + local_type_generic: deployment + remote_type_generic: cluster remote_type: Self-managed --- diff --git a/deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md b/deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md index 5e6e2cc0d3..229ef3bba0 100644 --- a/deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md +++ b/deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md @@ -9,6 +9,8 @@ applies_to: products: - id: cloud-enterprise sub: + local_type_generic: deployment + remote_type_generic: deployment remote_type: Elastic Cloud Hosted --- diff --git a/deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md b/deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md index 9acba46756..5db4adc173 100644 --- a/deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md +++ b/deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md @@ -8,6 +8,8 @@ applies_to: products: - id: cloud-enterprise sub: + local_type_generic: deployment + remote_type_generic: deployment remote_type: Elastic Cloud Enterprise --- diff --git a/deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md b/deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md index 8ca39a5f2f..74c4926c31 100644 --- a/deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md +++ b/deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md @@ -8,6 +8,8 @@ applies_to: products: - id: cloud-enterprise sub: + local_type_generic: deployment + remote_type_generic: deployment remote_type: Elastic Cloud Enterprise --- diff --git a/deploy-manage/remote-clusters/ece-remote-cluster-self-managed.md b/deploy-manage/remote-clusters/ece-remote-cluster-self-managed.md index 5a784be67e..7582a5823f 100644 --- a/deploy-manage/remote-clusters/ece-remote-cluster-self-managed.md +++ b/deploy-manage/remote-clusters/ece-remote-cluster-self-managed.md @@ -9,6 +9,8 @@ applies_to: products: - id: cloud-enterprise sub: + local_type_generic: deployment + remote_type_generic: cluster remote_type: Self-managed --- diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md index 4d1f5f3f7d..19bc5f0a54 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md @@ -5,48 +5,101 @@ applies_to: eck: ga products: - id: cloud-kubernetes +sub: + local_type_generic: cluster + remote_type_generic: cluster + remote_type: Self-managed --- -# Connect a self-managed {{es}} cluster to an ECK-managed cluster +# Connect a self-managed {{es}} cluster to an ECK-managed cluster [self-to-eck-remote-clusters] -This guide explains how to configure remote cluster connections from an external {{es}} cluster to a cluster managed by ECK. +These steps describe how to configure remote clusters between a self-managed {{es}} cluster and an {{es}} cluster managed by [{{eck}} (ECK)](/deploy-manage/deploy/cloud-on-k8s.md). Once that’s done, you’ll be able to [run CCS queries from {{es}}](/solutions/search/cross-cluster-search.md) or [set up CCR](/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md). -(title update from the original "Connect from an Elasticsearch cluster running outside the Kubernetes cluster") --> This had ONLY TLS certs (deprecated) -(existing use case with TLS certs, API key missing) - -::::{include} _snippets/eck_rcs_intro.md -:::: +If the local deployment is on ECH or ECE, refer to: +- EC doc +- ECE doc +For other remote cluster scenarios with ECK, refer to [Remote clusters on ECK](./eck-remote-clusters-landing.md). -(note and links to other possible use cases and landing page) Intro, if the external cluster is managed by a different ECK, refer to "to external". Intro: this doc assumes the local cluster is a self-managed cluster. -from an external scope: only from self-managed to ECK, because: -- From ECH/ECE to ECK already exist. -- From ECK to ECK (in to external). +:::{include} _snippets/terminology.md +::: +## Allow the remote connection [ec_allow_the_remote_connection_4] -### Using the API key security model +:::{include} _snippets/allow-connection-intro.md +::: -If the local deployment is on ECH or ECE, refer to: -- EC doc -- ECE doc +:::::::{tab-set} -(TBD) - similar steps than EC/ECE to here. -1. Enable remote cluster server in the remote cluster +::::::{tab-item} API key -2. Create API key in remote cluster +:::{include} _snippets/apikeys-intro.md +::: -3. Expose and obtain CA of the remote +### Prerequisites and limitations [ec_prerequisites_and_limitations_4] -3. +:::{include} _snippets/apikeys-prerequisites-limitations.md +::: + +GPT: +- You must have administrative access to the self-managed {{es}} cluster (API or filesystem access). +- The self-managed cluster must be able to establish outbound TLS connections to the remote cluster server endpoint exposed by the ECK-managed cluster. + +### Enable the remote cluster server interface on the remote ECK cluster + +:::{include} _snippets/eck_rcs_enable.md +::: + +### Configure external access to the remote cluster server interface + +:::{include} _snippets/eck_rcs_expose.md +::: + + +### Retrieve the ECK-managed CA certificate of the remote cluster server [fetch-ca-cert] + +:::{include} _snippets/eck_rcs_retrieve_ca.md +::: + +### Create a cross-cluster API key on the remote cluster [ec_create_a_cross_cluster_api_key_on_the_remote_deployment_4] + +:::{include} _snippets/apikeys-create-key.md +::: + + +### Configure the local deployment [ec_configure_the_local_deployment_2] + +:::{include} _snippets/apikeys-local-config-intro.md +::: + +The steps to follow depend on whether the certificate authority (CA) presented by the remote cluster server, proxy, or load-balancing infrastructure is publicly trusted or private. + +::::{dropdown} The CA is public + +Needs to be done, ECH snippet is not valid. + +:::: + +::::{dropdown} The CA is private (ECK-managed transport certificates) + +When adding the CA certificate in the next steps, use either the ECK-managed transport CA obtained [previously](#fetch-ca-cert), or the CA of the component that terminates TLS connections to clients. + +Needs to be done, ECH snippet is not valid. + +:::: + +:::::: + +::::::{tab-item} TLS certificate (deprecated) + +### Establish mutual trust between the clusters [ec_establish_trust_between_two_clusters] +#### Establish trust in the ECH cluster [ec_establish_trust_in_the_elasticsearch_service_cluster] +#### Establish trust in the ECK cluster [ec_establish_trust_in_the_eck_cluster] -### Using the certificate security model -```{applies_to} -stack: deprecated 9.0 -``` ::::{note} While it is technically possible to configure remote cluster connections using older versions of {{es}}, this guide only covers the setup for {{es}} 7.6 and later. The setup process is significantly simplified in {{es}} 7.6 due to improved support for the indirection of Kubernetes services. @@ -113,8 +166,7 @@ If `cluster-two` is also managed by an ECK instance, proceed as follows: 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 {{es}} REST API [k8s_configure_the_remote_cluster_connection_through_the_elasticsearch_rest_api] +### Configure external access to the transport interface of your ECK cluster Expose the transport layer of `cluster-one`. @@ -132,6 +184,19 @@ spec: 1. On cloud providers which support external load balancers, setting the type field to LoadBalancer provisions a load balancer for your Service. Alternatively, expose the service through one of the Kubernetes Ingress controllers that support TCP services. +**Include to compare:** + +:::{include} _snippets/eck_expose_transport.md +::: + +:::::: +::::::: + +## Connect to the remote cluster [ec_connect_to_the_remote_cluster_4] + +Esto viene de TLS, hay que ver si los otros metodos valen, que seguro que sí! + +H4 - Configure the remote cluster connection through the {{es}} REST API: Finally, configure `cluster-one` as a remote cluster in `cluster-two` using the {{es}} REST API: @@ -155,5 +220,20 @@ PUT _cluster/settings 2. Replace `${LOADBALANCER_IP}` with the IP address assigned to the `LoadBalancer` configured in the previous code sample. If you have configured a DNS entry for the service, you can use the DNS name instead of the IP address as well. +:::{include} _snippets/eck_rcs_connect_intro.md +::: + +### Using {{kib}} [ec_using_kibana_4] + +:::{include} _snippets/rcs-kibana-api-snippet-self.md +::: + +### Using the {{es}} API [ec_using_the_elasticsearch_api_4] + +:::{include} _snippets/rcs-elasticsearch-api-snippet-self.md +::: +## Configure roles and users [ec_configure_roles_and_users_4] +:::{include} _snippets/configure-roles-and-users.md +::: diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-landing.md b/deploy-manage/remote-clusters/eck-remote-clusters-landing.md index b58a1afd1e..6cd38f018b 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters-landing.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters-landing.md @@ -29,7 +29,7 @@ To use CCS or CCR, your {{es}} clusters must meet the following criteria: :::{include} _snippets/remote-cluster-certificate-compatibility.md ::: -* Network connectivity between the clusters. Review the [connection modes](./remote-cluster-connection-modes.md) and the [security models](./security-models.md) to understand the connectivity requirements for your specific setup. Remote cluster connections can operate through Kubernetes services, load balancers, reverse proxies, or other intermediaries, as long as the local cluster can reach the remote cluster’s endpoint. +* Network connectivity between the clusters. Review the [connection modes](./connection-modes.md) and the [security models](./security-models.md) to understand the connectivity requirements for your specific setup. Remote cluster connections can operate through Kubernetes services, load balancers, reverse proxies, or other intermediaries, as long as the local cluster can reach the remote cluster’s endpoint. * The remote clusters feature on ECK requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../license/manage-your-license-in-eck.md) for more details about managing licenses. @@ -39,7 +39,7 @@ Use one of the following guides depending on how the local and remote clusters a Connect from ECK-managed clusters: - - [Connect to {{es}} clusters in the same ECK environment](./eck-remote-clusters-same-eck.md) + - [Connect to {{es}} clusters in the same ECK environment](./eck-remote-clusters.md) - [Connect to external {{es}} clusters or deployments](./eck-remote-clusters-to-external.md) Connect to ECK-managed clusters from external clusters: diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md index 86f904f41e..4addb739ac 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md @@ -1,40 +1,354 @@ --- -navigation_title: To an external cluster +navigation_title: To an external cluster or deployment applies_to: deployment: eck: ga products: - id: cloud-kubernetes +sub: + local_type_generic: cluster + remote_type_generic: deployment or cluster --- -# Connect an ECK-managed cluster to an external {{es}} cluster -(Use case missing). +# Connect an ECK-managed cluster to an external cluster or deployment -This guide explains how to configure remote clusters when your ECK-managed cluster connects to a self-managed cluster, an ECE/ECH deployment, or a cluster managed by another ECK operator. +% process described here: https://github.com/elastic/cloud-on-k8s/issues/8502#issuecomment-2753674140 (for ECH) +These steps describe how to configure remote clusters between an {{es}} cluster managed by {{eck}} (ECK) and an external {{es}} cluster, using the [API key based](./security-models.md) security model. The remote cluster can be self-managed, part of an {{ech}} (ECH) or {{ece}} (ECE) deployment, or managed by a different ECK operator. -::::{include} _snippets/eck_rcs_intro.md +Once the connection is established, you’ll be able to [run CCS queries from {{es}}](/solutions/search/cross-cluster-search.md) or [set up CCR](/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md). + +:::{include} _snippets/terminology.md +::: + +In this scenario, most of the configuration must be performed manually, as {{eck}} cannot orchestrate the setup across both clusters. For fully automated configuration between ECK-managed clusters, refer to [Connect to {{es}} clusters in the same ECK environment](./eck-remote-clusters.md). + +For other remote cluster scenarios with ECK, refer to [Remote clusters on ECK](./eck-remote-clusters-landing.md#eck-rcs-setup). + +## Allow the remote connection [ec_allow_the_remote_connection_4] + +% consider replacing this intro +:::{include} _snippets/apikeys-intro.md +::: + +### Enable the remote cluster server interface on the remote cluster [enable-rcs] + +Follow the steps corresponding to the deployment type of your remote cluster: + +:::::::{tab-set} + +::::::{tab-item} ECH +If the remote cluster is part of an {{ech}} deployment, the remote cluster server is enabled by default and it uses a publicly trusted certificate provided by the platform proxies. Therefore, you can skip this step. +:::::: + +::::::{tab-item} ECE +If the remote cluster is part of an {{ece}} deployment, the remote cluster server is enabled by default, and secured with TLS certificates. + +Depending on the type of certificates used by the ECE proxies or load-balancing layer, the CA certificate may be needed by the local cluster to establish trust: + +* If your ECE proxies use publicly trusted certificates, no additional CA is required. + +* If your ECE proxies use certificates signed by a private CA, retrieve the root CA from the [ECE Cloud UI](/deploy-manage/deploy/cloud-enterprise/log-into-cloud-ui.md): + + 1. In the remote ECE environment, go to **Platform > Settings > TLS certificates**. + + 2. Under **Proxy**, select **Show certificate chain**. + + 3. Click **Copy root certificate** and paste it into a new file. The root certificate is the last certificate shown in the chain. + + 4. Save the file as `.crt`, and keep it available for the trust configuration on the local cluster. +:::::: + +::::::{tab-item} ECK +If the remote cluster is managed by a different ECK environment, it must be prepared to accept incoming connections. + +1. **Enable the remote cluster server** + + :::{include} _snippets/eck_rcs_enable.md + ::: + +2. **Expose the remote cluster server interface** + + :::{include} _snippets/eck_rcs_expose.md + ::: + +3. **Retrieve the certificate authority (CA)** + + :::{include} _snippets/eck_rcs_retrieve_ca.md + ::: + +:::::: +::::::{tab-item} Self-managed + +1. **Enable the remote cluster server** + + :::{include} _snippets/self_rcs_enable.md + ::: + +2. **Retrieve the certificate authority (CA)** + + If the remote cluster server is exposed with a certificate signed by private certificate authority (CA), save the corresponding `ca.crt` file. It is required when configuring trust on the local cluster. + +:::::: +::::::: + + + +### Create a cross-cluster API key on the remote cluster [ec_create_a_cross_cluster_api_key_on_the_remote_deployment_4] + +:::{include} _snippets/apikeys-create-key.md +::: + +### Configure the local cluster [configure-local-cluster] + +:::{include} _snippets/apikeys-local-config-intro.md +::: + +The steps to follow depend on whether the certificate authority (CA) presented by the remote cluster server, proxy, or load-balancing infrastructure is publicly trusted or private. + +:::{note} +If the remote cluster is part of an {{ech}} deployment, follow the **The CA is public** path. {{ech}} proxies use publicly trusted certificates, so no CA configuration is required. +::: + +::::{dropdown} The CA is public + +1. **Store the API key encoded value in a Secret** + + :::{include} _snippets/eck_apikey_secret.md + ::: + +2. **Configure the {{es}} resource** + + Update the {{es}} manifest to: + * Load the API key using `secureSettings` + * Enable the remote-cluster SSL client in the `config` section of each `nodeSet` + + ```yaml subs=true + apiVersion: elasticsearch.k8s.elastic.co/v1 + kind: Elasticsearch + metadata: + name: + spec: + version: {{version.stack}} + secureSettings: + - secretName: remote-api-keys <1> + nodeSets: + - name: default + count: 3 + config: + xpack: + security: + remote_cluster_client: + ssl: + enabled: true <2> + ``` + 1. The secret name must match the secret created in the previous step. + 2. Repeat this configuration for all `nodeSets`. +:::: + +::::{dropdown} The CA is private + +1. **Store the API key encoded value in a Secret** + + :::{include} _snippets/eck_apikey_secret.md + ::: + +2. **Store the CA certificate in a ConfigMap or Secret** + + Store the CA certificate [retrieved earlier](#enable-rcs) in a ConfigMap or Secret, making it available to mount [as a custom file](/deploy-manage/deploy/cloud-on-k8s/custom-configuration-files-plugins.md#use-a-volume-and-volume-mount-together-with-a-configmap-or-secret) in the {{es}} Pods. + + The following example creates a ConfigMap named `remote-ca` that stores the content of a local file (`my-ca.crt`) under the `remote-cluster-ca.crt` key: + + ```sh + kubectl create configmap remote-ca -n --from-file=remote-cluster-ca.crt=my-ca.crt + ``` + +3. **Configure the {{es}} resource** + + Update the {{es}} manifest to: + * Load the API key from the secret using `secureSettings`. + * Mount the CA certificate from the ConfigMap in each `nodeSet`. + * Enable and configure the remote-cluster SSL client in the `config` section of each `nodeSet`. + + ```yaml subs=true + apiVersion: elasticsearch.k8s.elastic.co/v1 + kind: Elasticsearch + metadata: + name: + spec: + version: {{version.stack}} + secureSettings: + - secretName: remote-api-keys + nodeSets: <1> + - name: default + count: 3 + config: + xpack: + security: + remote_cluster_client: + ssl: + enabled: true + certificate_authorities: [ "remote-certs/remote-cluster-ca.crt" ] <2> + podTemplate: + spec: + containers: + - name: elasticsearch + volumeMounts: + - name: remote-ca + mountPath: /usr/share/elasticsearch/config/remote-certs + volumes: + - name: remote-ca + configMap: + name: remote-ca <3> + ``` + 1. Repeat this configuration for all `nodeSets`. + 2. The file name must match the `key` of the ConfigMap that contains the CA certificate. + 3. Must match the name of the ConfigMap created previously. :::: +## Connect to the remote cluster [ec_connect_to_the_remote_cluster_4] + +On the local cluster, add the remote cluster using {{kib}} or the {{es}} API. + +:::{admonition} About connection modes +This guide uses the `proxy` connection mode, which is the only practical option when connecting to {{ech}}, {{ece}}, or {{eck}} clusters from outside their Kubernetes environment. + +If the remote cluster is self-managed (or another ECK cluster within the same Kubernetes network) and the local cluster can reach the remote nodes’ publish addresses directly, you can use `sniff` mode instead. Refer to [connection modes](./connection-modes.md) documentation for details on each mode and their connectivity requirements. + +If you intend to use `sniff` mode, configure it through the [{{es}} API](#using-api). {{kib}} UI only supports `proxy` mode. +::: + +### Using {{kib}} [using-kibana] + +1. Go to the **Remote Clusters** management page in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). +2. Select **Add a remote cluster**. +3. In **Select connection type**, choose the **API keys** authentication mechanism 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. + + This alias must match the **Remote cluster name** you configured when [adding the API key in the local cluster's keystore](#configure-local-cluster). + + * **Remote address**: Identify the endpoint of the remote cluster, including the hostname, FQDN, or IP address, and the port: + + :::::::{tab-set} + + ::::::{tab-item} ECH + Obtain the endpoint from the **Security** page of the ECH deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters** section, and replace its port with `9443`, which is the port used by the remote cluster server interface. + + :::::: + + ::::::{tab-item} ECE + Obtain the endpoint from the **Security** page of the ECE deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters**, and replace its port with `9443`, which is the port used by the remote cluster server interface. + :::::: + + ::::::{tab-item} ECK + Use the FQDN or IP address of the LoadBalancer service, or similar resource, you created to [expose the remote cluster server interface](#enable-rcs). + :::::: + + ::::::{tab-item} Self-managed + Use the address of a TCP (layer 4) reverse proxy configured in your environment to route connections to one or more nodes of the cluster on port `9443`. + + If you intend to configure `sniff` mode with a list of {{es}} node addresses as `seeds` , use the [{{es}} API](#using-api) instead. + :::::: + ::::::: + + Starting with {{kib}} 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 {{es}} API [using-api] + +% :::{include} _snippets/rcs-elasticsearch-api-snippet-self.md +% ::: + +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`: The cluster alias must match the one you configured when [adding the API key in the local cluster's keystore](#configure-local-cluster). +* `mode`: Use `proxy` mode in almost all cases. `sniff` mode is only applicable for self-managed remote clusters where the local cluster can reach the nodes’ publish addresses directly. +* `proxy_address` (or `seeds` if sniff mode is used): + + Identify the endpoint of the remote cluster, including the hostname, FQDN, or IP address, and the port. Both IPv4 and IPv6 addresses are supported. + + :::::::{tab-set} + + ::::::{tab-item} ECH + Obtain the endpoint from the **Security** page of the ECH deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters** section, and replace its port with `9443`, which is the port used by the remote cluster server interface. + + :::::: + + ::::::{tab-item} ECE + Obtain the endpoint from the **Security** page of the ECE deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters**, and replace its port with `9443`, which is the port used by the remote cluster server interface. + :::::: + + ::::::{tab-item} ECK + Use the FQDN or IP address of the LoadBalancer service, or similar resource, you created to [expose the remote cluster server interface](#enable-rcs). + :::::: + + ::::::{tab-item} Self-managed + The endpoint depends on your network architecture and the selected connection mode (`sniff` or `proxy`). It can be one or more {{es}} nodes, or a load balancer or reverse proxy in front of the cluster, as long as the local cluster can reach them over port `9443`. + + Refer to the [connection modes](./connection-modes.md) documentation for details and connectivity requirements of each mode. + :::::: + ::::::: + + 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. -Intro, the external / remote cluster in this case could be ECH/ECE/self-managed or even an ECK-managed cluster managed by a different operator. +This is an example of the API call to add or update a remote cluster: -When the remote cluster is not handled by the same operator, there are certain things that the operator is not capable to do, so it requires some extra steps. +```json +PUT /_cluster/settings +{ + "persistent": { + "cluster": { + "remote": { + "alias-for-my-remote-cluster": { // Align the alias with the remote cluster name used when adding the API key as a secure setting. + "mode":"proxy", + "proxy_address": ":9443", + "server_name": "" + } + } + } + } +} +``` -(license considerations) +For a full list of available client connection settings in proxy mode, refer to the [remote cluster settings reference](elasticsearch://reference/elasticsearch/configuration-reference/remote-clusters.md#remote-cluster-proxy-settings). -This guide focuses on API key based authentication as the security model, as TLS cert based authentication is deprecated in favor of API. +## Verify remote cluster connection -Steps: -1. Enable the remote cluster server on the remote (if it's ECH or ECE it's enabled by default) -2. Create an API key on the remote, get CA certificate. -3. Create the connection from the local ECK-managed Elasticsearch cluster +In the local cluster, check the status of the connection to the remote cluster. If you run into any issues, refer to [Troubleshooting](/troubleshoot/elasticsearch/remote-clusters.md). -(note: the orchestrator does NOT help in this process at all... or would it help?) +```console +GET _remote/info +``` -process described here: https://github.com/elastic/cloud-on-k8s/issues/8502#issuecomment-2753674140 (for ECH) -(does it make sense to recreate N docs or try to create a single one?) -ECK to --> another ECK, self-managed, ECH, ECE. +In the response, look for the `connected` value: +``` +{ + "": { + "connected": true, + "mode": "proxy", + "proxy_address": ":9443", + "server_name": "", + "num_proxy_sockets_connected": 18, + "max_proxy_socket_connections": 18, + "initial_connect_timeout": "30s", + "skip_unavailable": true, + "cluster_credentials": "::es_redacted::" + } +} +``` +## Configure roles and users [ec_configure_roles_and_users_4] +:::{include} _snippets/configure-roles-and-users.md +::: diff --git a/deploy-manage/remote-clusters/eck-remote-clusters.md b/deploy-manage/remote-clusters/eck-remote-clusters.md index 23a3946c36..c2eca7743c 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters.md @@ -11,10 +11,7 @@ products: # Connect to {{es}} clusters in the same ECK environment [k8s-remote-clusters-connect-internal] -::::{include} _snippets/eck_rcs_intro.md -:::: - -This guide explains how to configure remote clusters when both the local and remote clusters are managed by the same ECK operator. For other remote cluster scenarios with ECK, refer to [Remote clusters on ECK](./eck-remote-clusters-landing.md). +These steps describe how to configure remote clusters between two {{es}} clusters that are managed by the same {{eck}} (ECK) operator. Once that’s done, you’ll be able to [run CCS queries from {{es}}](/solutions/search/cross-cluster-search.md) or [set up CCR](/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md). For other remote cluster scenarios with ECK, refer to [Remote clusters on ECK](./eck-remote-clusters-landing.md). ::::{note} The remote clusters feature requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../license/manage-your-license-in-eck.md) for more details about managing licenses. @@ -23,7 +20,7 @@ The remote clusters feature requires a valid Enterprise license or Enterprise tr ::::{include} _snippets/terminology.md :::: -To create a remote cluster connection to another {{es}} cluster deployed within the same Kubernetes cluster, specify the `remoteClusters` attribute in your {{es}} spec. +To create a remote cluster connection to another {{es}} cluster deployed in the same ECK environmnt, specify the `remoteClusters` attribute in your {{es}} spec. ## Security models [k8s_security_models] @@ -39,34 +36,21 @@ Based on the selected security model, use one of the following setup procedures. ::::::{tab-item} API key -### Enable the remote cluster server interface +:::{include} _snippets/apikeys-intro.md +::: -To enable the API key security model, you must first enable the remote cluster server on the remote {{es}} cluster by setting `spec.remoteClusterServer.enabled: true`: +### Enable the remote cluster server interface on the remote cluster -```yaml subs=true -apiVersion: elasticsearch.k8s.elastic.co/v1 -kind: Elasticsearch -metadata: - name: cluster-two - namespace: ns-two -spec: - version: {{version.stack}} - remoteClusterServer: - enabled: true - nodeSets: - - name: default - count: 3 -``` +:::{include} _snippets/eck_rcs_enable.md +::: -::::{note} -Enabling the remote cluster server triggers a restart of the {{es}} cluster. -:::: +### Configure the local cluster -### Add the remote cluster on the local cluster +Once the remote cluster server is enabled and running on the remote cluster, you can configure the {{es}} reference on the local cluster and include the desired permissions for cross-cluster search and cross-cluster replication under the `spec.remoteClusters` field. -Once the remote cluster server is enabled and running on the remote cluster, you can configure the {{es}} reference on the local cluster and 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 {{es}} resource is compatible with the [{{es}} 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. -Permissions have to be included under the `apiKey` field. The API model of the {{es}} resource is compatible with the [{{es}} 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: +The following example shows how to reference `cluster-two` as a remote cluster in `cluster-one` and specify the cross-cluster permissions under the `apiKey` field. ```yaml subs=true apiVersion: elasticsearch.k8s.elastic.co/v1 diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md index 6f45086b11..f4677643f3 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -43,7 +43,7 @@ If you run into any issues, refer to [Troubleshooting](/troubleshoot/elasticsear ::::{note} If a remote cluster is part of an {{ech}} (ECH) deployment, the remote cluster server is enabled by default and it uses a publicly trusted certificate provided by the platform proxies. Therefore, you can skip the following steps in these instructions: -**On the remote (ECH) cluster:** Skip steps 1-4 (enabling the service, generating certificates, configuring SSL settings, and restarting the cluster), and go directly to step 5 (create an API key). +**On the remote (ECH) cluster:** Skip steps 1-4 (enabling the service, generating certificates, configuring SSL settings, and restarting the cluster), and go directly to [create an API key](#create-api-key). **On the local (self-managed) cluster:** Do not add the `xpack.security.remote_cluster_client.ssl.certificate_authorities` setting to the configuration file because ECH uses publicly trusted certificates that don't require custom CA configuration. :::: @@ -51,67 +51,15 @@ If a remote cluster is part of an {{ech}} (ECH) deployment, the remote cluster s ### On the remote cluster [remote-clusters-security-api-key-remote-action] -1. Enable the remote cluster server on every node of the remote cluster. In [`elasticsearch.yml`](/deploy-manage/stack-settings.md): +#### Enable and secure the remote cluster server interface - 1. Set [`remote_cluster_server.enabled`](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#remote-cluster-network-settings) to `true`. - 2. Configure the bind and publish address for remote cluster server traffic, for example using [`remote_cluster.host`](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#remote-cluster-network-settings). Without configuring the address, remote cluster traffic may be bound to the local interface, and remote clusters running on other machines can’t connect. - 3. Optionally, configure the remote server port using [`remote_cluster.port`](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#remote_cluster.port) (defaults to `9443`). +:::{include} _snippets/self_rcs_enable.md +::: -2. Next, generate a certificate authority (CA) and a server certificate/key pair. On one of the nodes of the remote cluster, from the directory where {{es}} has been installed: +#### Create an API key [create-api-key] - 1. Create a CA, if you don’t have a CA already: - - ```sh - ./bin/elasticsearch-certutil ca --pem --out=cross-cluster-ca.zip --pass CA_PASSWORD - ``` - - Replace `CA_PASSWORD` with the password you want to use for the CA. You can remove the `--pass` option and its argument if you are not deploying to a production environment. - - 2. Unzip the generated `cross-cluster-ca.zip` file. This compressed file contains the following content: - - ```txt - /ca - |_ ca.crt - |_ ca.key - ``` - - 3. Generate a certificate and private key pair for the nodes in the remote cluster: - - ```sh - ./bin/elasticsearch-certutil cert --out=cross-cluster.p12 --pass=CERT_PASSWORD --ca-cert=ca/ca.crt --ca-key=ca/ca.key --ca-pass=CA_PASSWORD --dns= --ip=192.0.2.1 - ``` - - * Replace `CA_PASSWORD` with the CA password from the previous step. - * Replace `CERT_PASSWORD` with the password you want to use for the generated private key. - * Use the `--dns` option to specify the relevant DNS name for the certificate. You can specify it multiple times for multiple DNS. - * Use the `--ip` option to specify the relevant IP address for the certificate. You can specify it multiple times for multiple IP addresses. - - 4. If the remote cluster has multiple nodes, you can either: - - * create a single wildcard certificate for all nodes; - * or, create separate certificates for each node either manually or in batch with the [silent mode](elasticsearch://reference/elasticsearch/command-line-tools/certutil.md#certutil-silent). - -3. On every node of the remote cluster: - - 1. Copy the `cross-cluster.p12` file from the earlier step to the `config` directory. If you didn’t create a wildcard certificate, make sure you copy the correct node-specific p12 file. - 2. Add following configuration to [`elasticsearch.yml`](/deploy-manage/stack-settings.md): - - ```yaml - xpack.security.remote_cluster_server.ssl.enabled: true - xpack.security.remote_cluster_server.ssl.keystore.path: cross-cluster.p12 - ``` - - 3. Add the SSL keystore password to the {{es}} keystore: - - ```sh - ./bin/elasticsearch-keystore add xpack.security.remote_cluster_server.ssl.keystore.secure_password - ``` - - When prompted, enter the `CERT_PASSWORD` from the earlier step. - -4. Restart the remote cluster. -5. On the remote cluster, generate a cross-cluster API key that provides access to the indices you want to use for {{ccs}} or {{ccr}}. You can use the [Create Cross-Cluster API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key) API or [{{kib}}](../api-keys/elasticsearch-api-keys.md). -6. Copy the encoded key (`encoded` in the response) to a safe location. You will need it to connect to the remote cluster later. +:::{include} _snippets/apikeys-create-key.md +::: ### On the local cluster [remote-clusters-security-api-key-local-actions] From 8c49bb136cf4dffe2aee58283d8d7c24c40b258b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 1 Dec 2025 14:33:19 +0100 Subject: [PATCH 05/14] updating link --- deploy-manage/security/k8s-transport-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/security/k8s-transport-settings.md b/deploy-manage/security/k8s-transport-settings.md index 9f21f518bb..33a433867f 100644 --- a/deploy-manage/security/k8s-transport-settings.md +++ b/deploy-manage/security/k8s-transport-settings.md @@ -78,7 +78,7 @@ spec: When following the instructions in [Configure a custom Certificate Authority](#k8s-transport-ca) the issuance of certificates is orchestrated by the ECK operator and the operator needs access to the CAs private key. If this is undesirable it is also possible to configure node transport certificates without involving the ECK operator. The following two pre-requisites apply: 1. The tooling used must be able to issue individual certificates for each {{es}} node and dynamically add or remove certificates as the cluster scales up and down. -2. The ECK operator must be configured to be aware of the CA in use for the [remote cluster](../remote-clusters/eck-remote-clusters.md#k8s-remote-clusters-connect-external) support to work. +2. The ECK operator must be configured to be aware of the CA in use for the [remote cluster](../remote-clusters/eck-remote-clusters-from-external.md) support to work. The following example configuration using [cert-manager csi-driver](https://cert-manager.io/docs/projects/csi-driver/) and [trust-manager](https://cert-manager.io/docs/projects/trust-manager/) meets these two requirements: From 8975dfe5db7d9ef07509882789c1a86a75b8b97f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 1 Dec 2025 14:36:36 +0100 Subject: [PATCH 06/14] wip note --- .../remote-clusters/eck-remote-clusters-from-external.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md index 19bc5f0a54..3b7071c679 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md @@ -13,6 +13,8 @@ sub: # Connect a self-managed {{es}} cluster to an ECK-managed cluster [self-to-eck-remote-clusters] +(this doc is a WIP) + These steps describe how to configure remote clusters between a self-managed {{es}} cluster and an {{es}} cluster managed by [{{eck}} (ECK)](/deploy-manage/deploy/cloud-on-k8s.md). Once that’s done, you’ll be able to [run CCS queries from {{es}}](/solutions/search/cross-cluster-search.md) or [set up CCR](/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md). If the local deployment is on ECH or ECE, refer to: @@ -44,10 +46,7 @@ Intro: this doc assumes the local cluster is a self-managed cluster. :::{include} _snippets/apikeys-prerequisites-limitations.md ::: - -GPT: -- You must have administrative access to the self-managed {{es}} cluster (API or filesystem access). -- The self-managed cluster must be able to establish outbound TLS connections to the remote cluster server endpoint exposed by the ECK-managed cluster. +- extra reqs to include? ### Enable the remote cluster server interface on the remote ECK cluster From ef6e0e3230b8af0ec39c2cefe09e43b4a429d067 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Tue, 2 Dec 2025 10:59:18 +0100 Subject: [PATCH 07/14] to external refined, almost completed --- .../eck-remote-clusters-to-external.md | 66 ++++++++++--------- 1 file changed, 36 insertions(+), 30 deletions(-) diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md index 4addb739ac..3a178d112d 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md @@ -13,7 +13,7 @@ sub: # Connect an ECK-managed cluster to an external cluster or deployment % process described here: https://github.com/elastic/cloud-on-k8s/issues/8502#issuecomment-2753674140 (for ECH) -These steps describe how to configure remote clusters between an {{es}} cluster managed by {{eck}} (ECK) and an external {{es}} cluster, using the [API key based](./security-models.md) security model. The remote cluster can be self-managed, part of an {{ech}} (ECH) or {{ece}} (ECE) deployment, or managed by a different ECK operator. +These steps describe how to configure a remote cluster connection from an {{es}} cluster managed by {{eck}} (ECK) to an external {{es}} cluster, where external refers to any cluster not managed by the same ECK operator. The remote cluster can be self-managed, part of an {{ech}} (ECH) or {{ece}} (ECE) deployment, or managed by a different ECK operator. Once the connection is established, you’ll be able to [run CCS queries from {{es}}](/solutions/search/cross-cluster-search.md) or [set up CCR](/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md). @@ -24,6 +24,13 @@ In this scenario, most of the configuration must be performed manually, as {{eck For other remote cluster scenarios with ECK, refer to [Remote clusters on ECK](./eck-remote-clusters-landing.md#eck-rcs-setup). +% refine this note +:::{note} +This guide uses API key authentication as the [security model](./security-models.md), which is the recommended option and replaces the deprecated TLS certificate–based model. + +If you need to configure TLS certificate authentication for this scenario, refer to the steps in [Connect from an external cluster](./eck-remote-clusters-from-external.md) and create the remote in the opposite direction. The mutual-TLS trust setup steps the similar. +::: + ## Allow the remote connection [ec_allow_the_remote_connection_4] % consider replacing this intro @@ -34,16 +41,16 @@ For other remote cluster scenarios with ECK, refer to [Remote clusters on ECK](. Follow the steps corresponding to the deployment type of your remote cluster: -:::::::{tab-set} +:::::::{applies-switch} -::::::{tab-item} ECH +::::::{applies-item} ess: If the remote cluster is part of an {{ech}} deployment, the remote cluster server is enabled by default and it uses a publicly trusted certificate provided by the platform proxies. Therefore, you can skip this step. :::::: -::::::{tab-item} ECE +::::::{applies-item} ece: If the remote cluster is part of an {{ece}} deployment, the remote cluster server is enabled by default, and secured with TLS certificates. -Depending on the type of certificates used by the ECE proxies or load-balancing layer, the CA certificate may be needed by the local cluster to establish trust: +Depending on the type of certificate used by the ECE proxies or load-balancing layer, the local cluster requires the associated certificate authority (CA) to establish trust: * If your ECE proxies use publicly trusted certificates, no additional CA is required. @@ -58,8 +65,8 @@ Depending on the type of certificates used by the ECE proxies or load-balancing 4. Save the file as `.crt`, and keep it available for the trust configuration on the local cluster. :::::: -::::::{tab-item} ECK -If the remote cluster is managed by a different ECK environment, it must be prepared to accept incoming connections. +::::::{applies-item} eck: +If the remote cluster is managed by a different ECK operator, it must be prepared to accept incoming connections. 1. **Enable the remote cluster server** @@ -77,9 +84,9 @@ If the remote cluster is managed by a different ECK environment, it must be prep ::: :::::: -::::::{tab-item} Self-managed +::::::{applies-item} self: -1. **Enable the remote cluster server** +1. **Enable and secure the remote cluster server** :::{include} _snippets/self_rcs_enable.md ::: @@ -231,22 +238,22 @@ If you intend to use `sniff` mode, configure it through the [{{es}} API](#using- * **Remote address**: Identify the endpoint of the remote cluster, including the hostname, FQDN, or IP address, and the port: - :::::::{tab-set} + :::::::{applies-switch} - ::::::{tab-item} ECH + ::::::{applies-item} ess: Obtain the endpoint from the **Security** page of the ECH deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters** section, and replace its port with `9443`, which is the port used by the remote cluster server interface. :::::: - ::::::{tab-item} ECE + ::::::{applies-item} ece: Obtain the endpoint from the **Security** page of the ECE deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters**, and replace its port with `9443`, which is the port used by the remote cluster server interface. :::::: - ::::::{tab-item} ECK + ::::::{applies-item} eck: Use the FQDN or IP address of the LoadBalancer service, or similar resource, you created to [expose the remote cluster server interface](#enable-rcs). :::::: - ::::::{tab-item} Self-managed + ::::::{applies-item} self: Use the address of a TCP (layer 4) reverse proxy configured in your environment to route connections to one or more nodes of the cluster on port `9443`. If you intend to configure `sniff` mode with a list of {{es}} node addresses as `seeds` , use the [{{es}} API](#using-api) instead. @@ -269,31 +276,29 @@ If you intend to use `sniff` mode, configure it through the [{{es}} API](#using- 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`: The cluster alias must match the one you configured when [adding the API key in the local cluster's keystore](#configure-local-cluster). -* `mode`: Use `proxy` mode in almost all cases. `sniff` mode is only applicable for self-managed remote clusters where the local cluster can reach the nodes’ publish addresses directly. -* `proxy_address` (or `seeds` if sniff mode is used): - - Identify the endpoint of the remote cluster, including the hostname, FQDN, or IP address, and the port. Both IPv4 and IPv6 addresses are supported. +* **Remote cluster alias**: The cluster alias must match the one you configured when [adding the API key in the local cluster's keystore](#configure-local-cluster). +* **mode**: Use `proxy` mode in almost all cases. `sniff` mode is only applicable when the remote cluster is self-managed and the local cluster can reach the nodes’ publish addresses directly. +* **proxy_address**: Identify the endpoint of the remote cluster, including the hostname, FQDN, or IP address, and the port. Both IPv4 and IPv6 addresses are supported. - :::::::{tab-set} + :::::::{applies-switch} - ::::::{tab-item} ECH + ::::::{applies-item} ess: Obtain the endpoint from the **Security** page of the ECH deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters** section, and replace its port with `9443`, which is the port used by the remote cluster server interface. :::::: - ::::::{tab-item} ECE + ::::::{applies-item} ece: Obtain the endpoint from the **Security** page of the ECE deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters**, and replace its port with `9443`, which is the port used by the remote cluster server interface. :::::: - ::::::{tab-item} ECK + ::::::{applies-item} eck: Use the FQDN or IP address of the LoadBalancer service, or similar resource, you created to [expose the remote cluster server interface](#enable-rcs). :::::: - ::::::{tab-item} Self-managed - The endpoint depends on your network architecture and the selected connection mode (`sniff` or `proxy`). It can be one or more {{es}} nodes, or a load balancer or reverse proxy in front of the cluster, as long as the local cluster can reach them over port `9443`. - - Refer to the [connection modes](./connection-modes.md) documentation for details and connectivity requirements of each mode. + ::::::{applies-item} self: + The endpoint depends on your network architecture and the selected connection mode (`sniff` or `proxy`). It can be one or more {{es}} nodes, or a TCP (layer 4) load balancer or reverse proxy in front of the cluster, as long as the local cluster can reach them over port `9443`. + + If you are configuring `sniff` mode, set the **seeds** parameter instead of **proxy_address**. Refer to the [connection modes](./connection-modes.md) documentation for details and connectivity requirements of each mode. :::::: ::::::: @@ -320,17 +325,18 @@ PUT /_cluster/settings } ``` -For a full list of available client connection settings in proxy mode, refer to the [remote cluster settings reference](elasticsearch://reference/elasticsearch/configuration-reference/remote-clusters.md#remote-cluster-proxy-settings). +For a full list of available client connection settings, refer to the [remote cluster settings reference](elasticsearch://reference/elasticsearch/configuration-reference/remote-clusters.md). ## Verify remote cluster connection -In the local cluster, check the status of the connection to the remote cluster. If you run into any issues, refer to [Troubleshooting](/troubleshoot/elasticsearch/remote-clusters.md). +From the local cluster, check the status of the connection to the remote cluster. If you encounter issues, refer to the [Troubleshooting guide](/troubleshoot/elasticsearch/remote-clusters.md). ```console GET _remote/info ``` -In the response, look for the `connected` value: +In the response, verify that connected is `true`: + ``` { "": { From 8d409c5b8a3468033723dd40db427c89a7bcb569 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Wed, 3 Dec 2025 11:12:35 +0100 Subject: [PATCH 08/14] ready for review --- .../apikeys-prerequisites-limitations.md | 2 +- .../_snippets/eck_expose_transport.md | 8 +- .../_snippets/eck_rcs_connect_intro.md | 10 +- .../rcs-elasticsearch-api-snippet-self.md | 3 +- .../_snippets/rcs-kibana-api-snippet-self.md | 3 +- .../_snippets/self_rcs_local_config.md | 30 +++ .../eck-remote-clusters-from-external.md | 198 ++++++------------ .../eck-remote-clusters-to-external.md | 21 +- .../remote-clusters/eck-remote-clusters.md | 38 ++-- .../remote-clusters-api-key.md | 27 +-- 10 files changed, 143 insertions(+), 197 deletions(-) create mode 100644 deploy-manage/remote-clusters/_snippets/self_rcs_local_config.md diff --git a/deploy-manage/remote-clusters/_snippets/apikeys-prerequisites-limitations.md b/deploy-manage/remote-clusters/_snippets/apikeys-prerequisites-limitations.md index 1619df67e1..d4af2ad70f 100644 --- a/deploy-manage/remote-clusters/_snippets/apikeys-prerequisites-limitations.md +++ b/deploy-manage/remote-clusters/_snippets/apikeys-prerequisites-limitations.md @@ -1,2 +1,2 @@ * The local and remote deployments must be on {{stack}} 8.14 or later. -* Contrary to the certificate security model, the API key security model does not require that both local and remote clusters trust each other. +* 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. \ No newline at end of file diff --git a/deploy-manage/remote-clusters/_snippets/eck_expose_transport.md b/deploy-manage/remote-clusters/_snippets/eck_expose_transport.md index a3308a1de4..5de660cc74 100644 --- a/deploy-manage/remote-clusters/_snippets/eck_expose_transport.md +++ b/deploy-manage/remote-clusters/_snippets/eck_expose_transport.md @@ -1,10 +1,16 @@ + Expose the transport service (defaults to port `9300`) of your ECK cluster to allow external {{es}} clusters to connect: ```yaml apiVersion: elasticsearch.k8s.elastic.co/v1 kind: Elasticsearch metadata: - name: + name: spec: transport: service: diff --git a/deploy-manage/remote-clusters/_snippets/eck_rcs_connect_intro.md b/deploy-manage/remote-clusters/_snippets/eck_rcs_connect_intro.md index ffb9cba4b8..953b14dde7 100644 --- a/deploy-manage/remote-clusters/_snippets/eck_rcs_connect_intro.md +++ b/deploy-manage/remote-clusters/_snippets/eck_rcs_connect_intro.md @@ -1,4 +1,12 @@ -On the local deployment, add the remote ECK cluster using {{kib}} or the {{es}} API with the following connection settings: + +On the local {{local_type_generic}}, add the remote ECK cluster using {{kib}} or the {{es}} API with the following connection settings: * **Remote address**: Use the FQDN or IP address of the LoadBalancer service, or similar resource, you created to expose the remote cluster server interface (for API key-based authentication) or the transport interface (for TLS certificate-based authentication). diff --git a/deploy-manage/remote-clusters/_snippets/rcs-elasticsearch-api-snippet-self.md b/deploy-manage/remote-clusters/_snippets/rcs-elasticsearch-api-snippet-self.md index 1060e90113..f1fe065a5e 100644 --- a/deploy-manage/remote-clusters/_snippets/rcs-elasticsearch-api-snippet-self.md +++ b/deploy-manage/remote-clusters/_snippets/rcs-elasticsearch-api-snippet-self.md @@ -4,10 +4,11 @@ This snippet is in use in the following locations: - ec-remote-cluster-self-managed.md - ece-enable-ccs-for-eck.md - ec-enable-ccs-for-eck.md +- eck-remote-clusters-from-external.md --> 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 in the Cloud UI as **Remote cluster name**. +* `Remote cluster alias`: When using API key authentication, the cluster alias must match the one you configured when adding the API key. * `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. diff --git a/deploy-manage/remote-clusters/_snippets/rcs-kibana-api-snippet-self.md b/deploy-manage/remote-clusters/_snippets/rcs-kibana-api-snippet-self.md index 25f580826c..8b567d02de 100644 --- a/deploy-manage/remote-clusters/_snippets/rcs-kibana-api-snippet-self.md +++ b/deploy-manage/remote-clusters/_snippets/rcs-kibana-api-snippet-self.md @@ -4,6 +4,7 @@ This snippet is in use in the following locations: - ec-remote-cluster-self-managed.md - ece-enable-ccs-for-eck.md - ec-enable-ccs-for-eck.md +- eck-remote-clusters-from-external.md --> 1. Go to the **Remote Clusters** management page in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). 2. Select **Add a remote cluster**. @@ -13,7 +14,7 @@ This snippet is in use in the following locations: * **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 in the Cloud UI. + When using API key authentication, this alias must match the **Remote cluster name** you configured when adding the API key. * **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: diff --git a/deploy-manage/remote-clusters/_snippets/self_rcs_local_config.md b/deploy-manage/remote-clusters/_snippets/self_rcs_local_config.md new file mode 100644 index 0000000000..08c53267b9 --- /dev/null +++ b/deploy-manage/remote-clusters/_snippets/self_rcs_local_config.md @@ -0,0 +1,30 @@ + +1. On every node of the local cluster: + + 1. Copy the `ca.crt` file generated on the remote cluster earlier into the `config` directory, renaming the file `remote-cluster-ca.crt`. + 2. Add following configuration to [`elasticsearch.yml`](/deploy-manage/stack-settings.md): + + ```yaml + xpack.security.remote_cluster_client.ssl.enabled: true + xpack.security.remote_cluster_client.ssl.certificate_authorities: [ "remote-cluster-ca.crt" ] + ``` + + ::::{tip} + If the remote cluster uses a publicly trusted certificate, don't include the `certificate_authorities` setting. This example assumes the remote is using the private certificates [created earlier](#remote-clusters-security-api-key-remote-action), which require the CA to be added. + :::: + + 3. Add the cross-cluster API key, created on the remote cluster earlier, to the keystore: + + ```sh + ./bin/elasticsearch-keystore add cluster.remote.ALIAS.credentials + ``` + + Replace `ALIAS` with the same name that you will use to create the remote cluster entry later. When prompted, enter the encoded cross-cluster API key created on the remote cluster earlier. + +2. Restart the local cluster to load changes to the keystore and settings. + + If you are configuring only the cross-cluster API key, you can use the [Nodes reload secure settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-reload-secure-settings) instead of restarting the cluster. Configuring the `remote_cluster_client` settings in `elasticsearch.yml` still requires a restart. diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md index 3b7071c679..9a0d503af2 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md @@ -8,28 +8,22 @@ products: sub: local_type_generic: cluster remote_type_generic: cluster - remote_type: Self-managed + remote_type: ECK-managed --- # Connect a self-managed {{es}} cluster to an ECK-managed cluster [self-to-eck-remote-clusters] -(this doc is a WIP) +These steps describe how to configure a remote cluster connection to an ECK-managed {{es}} cluster from another cluster running outside the Kubernetes cluster. Once that’s done, you’ll be able to [run CCS queries from {{es}}](/solutions/search/cross-cluster-search.md) or [set up CCR](/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md). -These steps describe how to configure remote clusters between a self-managed {{es}} cluster and an {{es}} cluster managed by [{{eck}} (ECK)](/deploy-manage/deploy/cloud-on-k8s.md). Once that’s done, you’ll be able to [run CCS queries from {{es}}](/solutions/search/cross-cluster-search.md) or [set up CCR](/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md). +:::{include} _snippets/terminology.md +::: -If the local deployment is on ECH or ECE, refer to: -- EC doc -- ECE doc +If the local cluster is part of an {{ech}} or {{ece}} deployment, and the remote cluster is managed by ECK, refer to: +- [](./ec-enable-ccs-for-eck.md) +- [](./ece-enable-ccs-for-eck.md) For other remote cluster scenarios with ECK, refer to [Remote clusters on ECK](./eck-remote-clusters-landing.md). -Intro, if the external cluster is managed by a different ECK, refer to "to external". -Intro: this doc assumes the local cluster is a self-managed cluster. - - -:::{include} _snippets/terminology.md -::: - ## Allow the remote connection [ec_allow_the_remote_connection_4] :::{include} _snippets/allow-connection-intro.md @@ -42,148 +36,108 @@ Intro: this doc assumes the local cluster is a self-managed cluster. :::{include} _snippets/apikeys-intro.md ::: -### Prerequisites and limitations [ec_prerequisites_and_limitations_4] +#### Prerequisites and limitations [ec_prerequisites_and_limitations_4] :::{include} _snippets/apikeys-prerequisites-limitations.md ::: -- extra reqs to include? -### Enable the remote cluster server interface on the remote ECK cluster +#### Enable the remote cluster server interface on the remote ECK cluster :::{include} _snippets/eck_rcs_enable.md ::: -### Configure external access to the remote cluster server interface +#### Configure external access to the remote cluster server interface :::{include} _snippets/eck_rcs_expose.md ::: - -### Retrieve the ECK-managed CA certificate of the remote cluster server [fetch-ca-cert] +#### Retrieve the ECK-managed CA certificate of the remote cluster server [fetch-ca-cert] :::{include} _snippets/eck_rcs_retrieve_ca.md ::: -### Create a cross-cluster API key on the remote cluster [ec_create_a_cross_cluster_api_key_on_the_remote_deployment_4] +#### Create a cross-cluster API key on the remote cluster [ec_create_a_cross_cluster_api_key_on_the_remote_deployment_4] :::{include} _snippets/apikeys-create-key.md ::: - -### Configure the local deployment [ec_configure_the_local_deployment_2] +#### Configure the local deployment [ec_configure_the_local_deployment_2] :::{include} _snippets/apikeys-local-config-intro.md ::: -The steps to follow depend on whether the certificate authority (CA) presented by the remote cluster server, proxy, or load-balancing infrastructure is publicly trusted or private. - -::::{dropdown} The CA is public - -Needs to be done, ECH snippet is not valid. - -:::: - -::::{dropdown} The CA is private (ECK-managed transport certificates) - -When adding the CA certificate in the next steps, use either the ECK-managed transport CA obtained [previously](#fetch-ca-cert), or the CA of the component that terminates TLS connections to clients. - -Needs to be done, ECH snippet is not valid. - -:::: +:::{include} _snippets/self_rcs_local_config.md +::: :::::: ::::::{tab-item} TLS certificate (deprecated) -### Establish mutual trust between the clusters [ec_establish_trust_between_two_clusters] -#### Establish trust in the ECH cluster [ec_establish_trust_in_the_elasticsearch_service_cluster] -#### Establish trust in the ECK cluster [ec_establish_trust_in_the_eck_cluster] +#### Make sure both clusters trust each other’s certificate authority [k8s_make_sure_both_clusters_trust_each_others_certificate_authority] +When using TLS certificate–based authentication, the first step is to establish mutual trust between the clusters at the transport layer. This requires exchanging and trusting each cluster’s transport certificate authority (CA): +* The CA of the remote (ECK-managed) cluster must be added as a trusted CA in the local cluster, +* The local cluster’s transport CA must be added as a trusted CA in the remote cluster. ::::{note} While it is technically possible to configure remote cluster connections using older versions of {{es}}, this guide only covers the setup for {{es}} 7.6 and later. The setup process is significantly simplified in {{es}} 7.6 due to improved support for the indirection of Kubernetes services. :::: -You can configure a remote cluster connection to an ECK-managed {{es}} 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 {{es}} 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 +* `remote-cluster` resides inside Kubernetes and is managed by ECK +* `local-cluster` is not hosted inside the same Kubernetes cluster as `remote-cluster` and may not even be managed by ECK -To configure `cluster-one` as a remote cluster in `cluster-two`: +To allow mutual TLS authentication between the clusters: -#### Make sure both clusters trust each other’s certificate authority [k8s_make_sure_both_clusters_trust_each_others_certificate_authority] - -The certificate authority (CA) used by ECK to issue certificates for the {{es}} transport layer is stored in a secret named `-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`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#_pem_encoded_files_3). - -::::{note} -Beware of copying the source Secret as-is into a different namespace. Check [Common Problems: Owner References](../../troubleshoot/deployments/cloud-on-k8s/common-problems.md#k8s-common-problems-owner-refs) for more information. -:::: - - -::::{note} -CA certificates are automatically rotated after one year by default. You can [configure](../deploy/cloud-on-k8s/configure-eck.md) this period. Make sure to keep the copy of the certificates Secret up-to-date. -:::: +1. The certificate authority (CA) used by ECK to issue certificates for the {{es}} transport layer is stored in a secret named `-es-transport-certs-public`. Extract the certificate for `remote-cluster` as follows: + ```sh + kubectl get secret remote-cluster-es-transport-certs-public \ + -o go-template='{{index .data "ca.crt" | base64decode}}' > remote.ca.crt + ``` -If `cluster-two` is also managed by an ECK instance, proceed as follows: + ::::{note} + Beware of copying the source secret as-is into a different namespace. Check [Common Problems: Owner References](../../troubleshoot/deployments/cloud-on-k8s/common-problems.md#k8s-common-problems-owner-refs) for more information. + :::: -1. Create a config map with the CA certificate you just extracted: + ::::{note} + CA certificates are automatically rotated after one year by default. You can [configure](../deploy/cloud-on-k8s/configure-eck.md) this period. Make sure to keep the copy of the certificates secret up-to-date. + :::: - ```sh - kubectl create configmap remote-certs --from-file=ca.crt=remote.ca.crt - ``` +2. Configure `local-cluster` to trust the transport CA of the remote cluster: -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 - ``` + If `local-cluster` is hosted outside of Kubernetes, take the CA certificate that you extracted previously and add it to the list of CAs in [`xpack.security.transport.ssl.certificate_authorities`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#_pem_encoded_files_3). -3. Repeat steps 1 and 2 to add the CA of `cluster-two` to `cluster-one` as well. + If `local-cluster` is also managed by an ECK instance, proceed as follows: -### Configure external access to the transport interface of your ECK cluster + 1. Create a config map with the CA certificate you just extracted: -Expose the transport layer of `cluster-one`. + ```sh + kubectl create configmap remote-certs --from-file=ca.crt=remote.ca.crt + ``` -```yaml -apiVersion: elasticsearch.k8s.elastic.co/v1 -kind: Elasticsearch -metadata: - name: cluster-one -spec: - transport: - service: - spec: - type: LoadBalancer <1> -``` + 2. Use this config map to configure `remote-cluster`'s CA as a trusted CA in `local-cluster`: -1. On cloud providers which support external load balancers, setting the type field to LoadBalancer provisions a load balancer for your Service. Alternatively, expose the service through one of the Kubernetes Ingress controllers that support TCP services. + ```yaml + apiVersion: elasticsearch.k8s.elastic.co/v1 + kind: Elasticsearch + metadata: + name: local-cluster + spec: + transport: + tls: + certificateAuthorities: + configMapName: remote-certs + nodeSets: + - count: 3 + name: default + version: 8.16.1 + ``` + +3. Repeat the previous steps to configure `remote-cluster` to trust the CA of the local cluster. -**Include to compare:** +#### Configure external access to the transport interface of the remote cluster :::{include} _snippets/eck_expose_transport.md ::: @@ -191,48 +145,22 @@ spec: :::::: ::::::: -## Connect to the remote cluster [ec_connect_to_the_remote_cluster_4] - -Esto viene de TLS, hay que ver si los otros metodos valen, que seguro que sí! - -H4 - Configure the remote cluster connection through the {{es}} REST API: - -Finally, configure `cluster-one` as a remote cluster in `cluster-two` using the {{es}} REST API: - -```sh -PUT _cluster/settings -{ - "persistent": { - "cluster": { - "remote": { - "cluster-one": { - "mode": "proxy", <1> - "proxy_address": "${LOADBALANCER_IP}:9300" <2> - } - } - } - } -} -``` - -1. Use "proxy" mode as `cluster-two` will be connecting to `cluster-one` through the Kubernetes service abstraction. -2. Replace `${LOADBALANCER_IP}` with the IP address assigned to the `LoadBalancer` configured in the previous code sample. If you have configured a DNS entry for the service, you can use the DNS name instead of the IP address as well. - +## Connect to the remote cluster :::{include} _snippets/eck_rcs_connect_intro.md ::: -### Using {{kib}} [ec_using_kibana_4] +### Using {{kib}} :::{include} _snippets/rcs-kibana-api-snippet-self.md ::: -### Using the {{es}} API [ec_using_the_elasticsearch_api_4] +### Using the {{es}} API :::{include} _snippets/rcs-elasticsearch-api-snippet-self.md ::: -## Configure roles and users [ec_configure_roles_and_users_4] +## Configure roles and users :::{include} _snippets/configure-roles-and-users.md ::: diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md index 3a178d112d..25d00d6b6b 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md @@ -12,7 +12,6 @@ sub: # Connect an ECK-managed cluster to an external cluster or deployment -% process described here: https://github.com/elastic/cloud-on-k8s/issues/8502#issuecomment-2753674140 (for ECH) These steps describe how to configure a remote cluster connection from an {{es}} cluster managed by {{eck}} (ECK) to an external {{es}} cluster, where external refers to any cluster not managed by the same ECK operator. The remote cluster can be self-managed, part of an {{ech}} (ECH) or {{ece}} (ECE) deployment, or managed by a different ECK operator. Once the connection is established, you’ll be able to [run CCS queries from {{es}}](/solutions/search/cross-cluster-search.md) or [set up CCR](/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md). @@ -126,8 +125,8 @@ If the remote cluster is part of an {{ech}} deployment, follow the **The CA is p 2. **Configure the {{es}} resource** Update the {{es}} manifest to: - * Load the API key using `secureSettings` - * Enable the remote-cluster SSL client in the `config` section of each `nodeSet` + * Load the API key from the previously created secret using [`secureSettings`](/deploy-manage/security/k8s-secure-settings.md) + * Enable the remote cluster SSL client in the `config` section of each `nodeSet` ```yaml subs=true apiVersion: elasticsearch.k8s.elastic.co/v1 @@ -161,9 +160,7 @@ If the remote cluster is part of an {{ech}} deployment, follow the **The CA is p 2. **Store the CA certificate in a ConfigMap or Secret** - Store the CA certificate [retrieved earlier](#enable-rcs) in a ConfigMap or Secret, making it available to mount [as a custom file](/deploy-manage/deploy/cloud-on-k8s/custom-configuration-files-plugins.md#use-a-volume-and-volume-mount-together-with-a-configmap-or-secret) in the {{es}} Pods. - - The following example creates a ConfigMap named `remote-ca` that stores the content of a local file (`my-ca.crt`) under the `remote-cluster-ca.crt` key: + Store the CA certificate [retrieved earlier](#enable-rcs) in a ConfigMap or Secret. The following example creates a ConfigMap named `remote-ca` that stores the content of a local file (`my-ca.crt`) under the `remote-cluster-ca.crt` key: ```sh kubectl create configmap remote-ca -n --from-file=remote-cluster-ca.crt=my-ca.crt @@ -172,9 +169,10 @@ If the remote cluster is part of an {{ech}} deployment, follow the **The CA is p 3. **Configure the {{es}} resource** Update the {{es}} manifest to: - * Load the API key from the secret using `secureSettings`. - * Mount the CA certificate from the ConfigMap in each `nodeSet`. - * Enable and configure the remote-cluster SSL client in the `config` section of each `nodeSet`. + + * Load the API key from the previously created secret using [`secureSettings`](/deploy-manage/security/k8s-secure-settings.md) + * Mount the CA certificate from the previously created ConfigMap [as a custom file](/deploy-manage/deploy/cloud-on-k8s/custom-configuration-files-plugins.md#use-a-volume-and-volume-mount-together-with-a-configmap-or-secret) in the {{es}} Pods + * Enable and configure the remote cluster SSL client in the `config` section of each `nodeSet` ```yaml subs=true apiVersion: elasticsearch.k8s.elastic.co/v1 @@ -271,9 +269,6 @@ If you intend to use `sniff` mode, configure it through the [{{es}} API](#using- ### Using the {{es}} API [using-api] -% :::{include} _snippets/rcs-elasticsearch-api-snippet-self.md -% ::: - 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**: The cluster alias must match the one you configured when [adding the API key in the local cluster's keystore](#configure-local-cluster). @@ -304,7 +299,7 @@ To add a remote cluster, use the [cluster update settings API](https://www.elast 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. +* **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: diff --git a/deploy-manage/remote-clusters/eck-remote-clusters.md b/deploy-manage/remote-clusters/eck-remote-clusters.md index c2eca7743c..525a5477b7 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters.md @@ -50,21 +50,21 @@ Once the remote cluster server is enabled and running on the remote cluster, you Permissions have to be included under the `apiKey` field. The API model of the {{es}} resource is compatible with the [{{es}} 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. -The following example shows how to reference `cluster-two` as a remote cluster in `cluster-one` and specify the cross-cluster permissions under the `apiKey` field. +The following example shows how to connect a local cluster to a remote cluster and specify the cross-cluster permissions under the `apiKey` field. This configuration is applied to the local cluster manifest: ```yaml subs=true apiVersion: elasticsearch.k8s.elastic.co/v1 kind: Elasticsearch metadata: - name: cluster-one - namespace: ns-one + name: + namespace: spec: version: {{version.stack}} remoteClusters: - - name: cluster-two + - name: elasticsearchRef: - name: cluster-two <1> - namespace: ns-two <2> + name: <1> + namespace: <2> apiKey: access: search: @@ -76,40 +76,40 @@ spec: nodeSets: - count: 3 name: default + ... + ... ``` 1. The name and namespace of the remote {{es}} cluster you are connecting to. 2. The namespace declaration can be omitted if both clusters reside in the same namespace. 3. This example requires the [{{kib}} sample data](/explore-analyze/index.md#gs-get-data-into-kibana). - You can find a complete example in the [recipes directory](https://github.com/elastic/cloud-on-k8s/tree/{{version.eck | M.M}}/config/recipes/remoteclusters). - :::::: ::::::{tab-item} TLS certificate (deprecated) -The following example describes how to configure `cluster-two` as a remote cluster in `cluster-one` using the certificate security model: +The following example shows how to connect a local cluster to a remote cluster using the certificate-based security model. The configuration is applied to the local cluster manifest: ```yaml apiVersion: elasticsearch.k8s.elastic.co/v1 kind: Elasticsearch metadata: - name: cluster-one - namespace: ns-one + name: + namespace: spec: + version: 8.16.1 + remoteClusters: + - name: + elasticsearchRef: + name: <1> + namespace: <2> nodeSets: - count: 3 name: default - remoteClusters: - - name: cluster-two - elasticsearchRef: - name: cluster-two <1> - namespace: ns-two <2> - version: 8.16.1 + ... + ... ``` 1. The name and namespace of the remote {{es}} cluster you are connecting to. 2. The namespace declaration can be omitted if both clusters reside in the same namespace. - - :::::: ::::::: diff --git a/deploy-manage/remote-clusters/remote-clusters-api-key.md b/deploy-manage/remote-clusters/remote-clusters-api-key.md index f4677643f3..11a26cc966 100644 --- a/deploy-manage/remote-clusters/remote-clusters-api-key.md +++ b/deploy-manage/remote-clusters/remote-clusters-api-key.md @@ -64,31 +64,8 @@ If a remote cluster is part of an {{ech}} (ECH) deployment, the remote cluster s ### On the local cluster [remote-clusters-security-api-key-local-actions] -1. On every node of the local cluster: - - 1. Copy the `ca.crt` file generated on the remote cluster earlier into the `config` directory, renaming the file `remote-cluster-ca.crt`. - 2. Add following configuration to [`elasticsearch.yml`](/deploy-manage/stack-settings.md): - - ```yaml - xpack.security.remote_cluster_client.ssl.enabled: true - xpack.security.remote_cluster_client.ssl.certificate_authorities: [ "remote-cluster-ca.crt" ] - ``` - - ::::{tip} - If the remote cluster uses a publicly trusted certificate, don't include the `certificate_authorities` setting. This example assumes the remote is using the private certificates [created earlier](#remote-clusters-security-api-key-remote-action), which require the CA to be added. - :::: - - 3. Add the cross-cluster API key, created on the remote cluster earlier, to the keystore: - - ```sh - ./bin/elasticsearch-keystore add cluster.remote.ALIAS.credentials - ``` - - Replace `ALIAS` with the same name that you will use to create the remote cluster entry later. When prompted, enter the encoded cross-cluster API key created on the remote cluster earlier. - -2. Restart the local cluster to load changes to the keystore and settings. - -**Note:** If you are configuring only the cross-cluster API key, you can call the [Nodes reload secure settings](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-nodes-reload-secure-settings) API, instead of restarting the cluster. Configuring the `remote_cluster_client` settings in `elasticsearch.yml` still requires a restart. +:::{include} _snippets/self_rcs_local_config.md +::: From 548d47491421217348ca8265eda3bc1c2ddbe7a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Wed, 3 Dec 2025 11:44:52 +0100 Subject: [PATCH 09/14] linting suggestions --- .../remote-clusters/_snippets/eck_apikey_secret.md | 2 +- deploy-manage/remote-clusters/_snippets/self_rcs_enable.md | 2 +- .../remote-clusters/eck-remote-clusters-from-external.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/deploy-manage/remote-clusters/_snippets/eck_apikey_secret.md b/deploy-manage/remote-clusters/_snippets/eck_apikey_secret.md index 932ddf4384..1036369c42 100644 --- a/deploy-manage/remote-clusters/_snippets/eck_apikey_secret.md +++ b/deploy-manage/remote-clusters/_snippets/eck_apikey_secret.md @@ -1,4 +1,4 @@ -The following command creates a secret with the API key encoded value obtained in the previous step: +The following command creates a secret containing the encoded API key obtained earlier: ```sh cat < Date: Wed, 3 Dec 2025 11:51:28 +0100 Subject: [PATCH 10/14] linting suggestions --- .../remote-clusters/_snippets/self_rcs_local_config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/remote-clusters/_snippets/self_rcs_local_config.md b/deploy-manage/remote-clusters/_snippets/self_rcs_local_config.md index 08c53267b9..0e14b57b62 100644 --- a/deploy-manage/remote-clusters/_snippets/self_rcs_local_config.md +++ b/deploy-manage/remote-clusters/_snippets/self_rcs_local_config.md @@ -23,7 +23,7 @@ This snippet is in use in the following locations: ./bin/elasticsearch-keystore add cluster.remote.ALIAS.credentials ``` - Replace `ALIAS` with the same name that you will use to create the remote cluster entry later. When prompted, enter the encoded cross-cluster API key created on the remote cluster earlier. + Replace `ALIAS` with the same name that you intend to use to create the remote cluster entry later. When prompted, enter the encoded cross-cluster API key created on the remote cluster earlier. 2. Restart the local cluster to load changes to the keystore and settings. From 708666df289ceacb1170cd0243c789547959a79b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Fri, 5 Dec 2025 13:10:51 +0100 Subject: [PATCH 11/14] added server name note for ECK remotes --- .../remote-clusters/eck-remote-clusters-to-external.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md index 25d00d6b6b..b7741377fb 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md @@ -249,6 +249,8 @@ If you intend to use `sniff` mode, configure it through the [{{es}} API](#using- ::::::{applies-item} eck: Use the FQDN or IP address of the LoadBalancer service, or similar resource, you created to [expose the remote cluster server interface](#enable-rcs). + + If your environment presents the ECK-managed certificates during the TLS handshake, configure the **TLS server name** advanced option as `-es-remote-cluster..svc`. Otherwise, the local cluster cannot establish the connection due to SSL trust errors. :::::: ::::::{applies-item} self: @@ -279,7 +281,6 @@ To add a remote cluster, use the [cluster update settings API](https://www.elast ::::::{applies-item} ess: Obtain the endpoint from the **Security** page of the ECH deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters** section, and replace its port with `9443`, which is the port used by the remote cluster server interface. - :::::: ::::::{applies-item} ece: @@ -287,7 +288,9 @@ To add a remote cluster, use the [cluster update settings API](https://www.elast :::::: ::::::{applies-item} eck: - Use the FQDN or IP address of the LoadBalancer service, or similar resource, you created to [expose the remote cluster server interface](#enable-rcs). + Use the FQDN or IP address of the LoadBalancer service, or similar resource, you created to [expose the remote cluster server interface](#enable-rcs). + + If your environment presents the ECK-managed certificates during the TLS handshake, configure the **server_name** field as `-es-remote-cluster..svc`. Otherwise, the local cluster cannot establish the connection due to SSL trust errors. :::::: ::::::{applies-item} self: From dcfb08c2541e5e4716698844918697890d3e0275 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Fri, 5 Dec 2025 14:25:50 +0100 Subject: [PATCH 12/14] added server name note for ECK remotes --- .../remote-clusters/eck-remote-clusters-to-external.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md index b7741377fb..4e364ad13c 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md @@ -288,7 +288,7 @@ To add a remote cluster, use the [cluster update settings API](https://www.elast :::::: ::::::{applies-item} eck: - Use the FQDN or IP address of the LoadBalancer service, or similar resource, you created to [expose the remote cluster server interface](#enable-rcs). + Use the FQDN or IP address of the LoadBalancer service, or similar resource, you created to [expose the remote cluster server interface](#enable-rcs) on port `9443`. If your environment presents the ECK-managed certificates during the TLS handshake, configure the **server_name** field as `-es-remote-cluster..svc`. Otherwise, the local cluster cannot establish the connection due to SSL trust errors. :::::: From 4a78cf863fd8523bcadadd36ddcce6f17cc858ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Fri, 5 Dec 2025 18:14:56 +0100 Subject: [PATCH 13/14] kibana UI and proxy mode related updates --- .../eck_rcs_external_endpoint_switch.md | 24 +++++++ .../eck-remote-clusters-to-external.md | 68 +++---------------- 2 files changed, 35 insertions(+), 57 deletions(-) create mode 100644 deploy-manage/remote-clusters/_snippets/eck_rcs_external_endpoint_switch.md diff --git a/deploy-manage/remote-clusters/_snippets/eck_rcs_external_endpoint_switch.md b/deploy-manage/remote-clusters/_snippets/eck_rcs_external_endpoint_switch.md new file mode 100644 index 0000000000..fc55c7e940 --- /dev/null +++ b/deploy-manage/remote-clusters/_snippets/eck_rcs_external_endpoint_switch.md @@ -0,0 +1,24 @@ +% Applies switch to identify the endpoint when configuring a remote cluster connection +::::::{applies-switch} + +:::::{applies-item} ess: +Obtain the endpoint from the **Security** page of the ECH deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters** section, and replace its port with `9443`, which is the port used by the remote cluster server interface. +::::: + +:::::{applies-item} ece: +Obtain the endpoint from the **Security** page of the ECE deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters**, and replace its port with `9443`, which is the port used by the remote cluster server interface. +::::: + +:::::{applies-item} eck: +Use the FQDN or IP address of the LoadBalancer service, or similar resource, you created to [expose the remote cluster server interface](#enable-rcs) on port `9443`. + +If your environment presents the ECK-managed certificates during the TLS handshake, configure the server name field as `-es-remote-cluster..svc`. Otherwise, the local cluster cannot establish the connection due to SSL trust errors. +::::: + +:::::{applies-item} self: +The endpoint depends on your network architecture and the selected connection mode (`sniff` or `proxy`). It can be one or more {{es}} nodes, or a TCP (layer 4) load balancer or reverse proxy in front of the cluster, as long as the local cluster can reach them over port `9443`. + +If you are configuring `sniff` mode, set the seeds parameter instead of the proxy address. Refer to the [connection modes](/deploy-manage/remote-clusters/connection-modes.md) documentation for details and connectivity requirements of each mode. +::::: +:::::: + diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md index 4e364ad13c..64a2cf08d2 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md @@ -218,53 +218,27 @@ On the local cluster, add the remote cluster using {{kib}} or the {{es}} API. This guide uses the `proxy` connection mode, which is the only practical option when connecting to {{ech}}, {{ece}}, or {{eck}} clusters from outside their Kubernetes environment. If the remote cluster is self-managed (or another ECK cluster within the same Kubernetes network) and the local cluster can reach the remote nodes’ publish addresses directly, you can use `sniff` mode instead. Refer to [connection modes](./connection-modes.md) documentation for details on each mode and their connectivity requirements. - -If you intend to use `sniff` mode, configure it through the [{{es}} API](#using-api). {{kib}} UI only supports `proxy` mode. ::: ### Using {{kib}} [using-kibana] +% ECK and self-managed clusters present a different Kibana UI when adding remote clusters than ECE/ECH deployments + 1. Go to the **Remote Clusters** management page in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). 2. Select **Add a remote cluster**. 3. In **Select connection type**, choose the **API keys** authentication mechanism and click **Next**. +4. Set the **Remote cluster name**: This name must match the `` you configured when [adding the API key in the local cluster's keystore](#configure-local-cluster). -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. +5. In **Connection mode**, select **Manually enter proxy address and server name** to enable the proxy mode and fill in the following fields: - This alias must match the **Remote cluster name** you configured when [adding the API key in the local cluster's keystore](#configure-local-cluster). - - * **Remote address**: Identify the endpoint of the remote cluster, including the hostname, FQDN, or IP address, and the port: + * **Proxy address**: Identify the endpoint of the remote cluster, including the hostname, FQDN, or IP address, and the port: - :::::::{applies-switch} - - ::::::{applies-item} ess: - Obtain the endpoint from the **Security** page of the ECH deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters** section, and replace its port with `9443`, which is the port used by the remote cluster server interface. - - :::::: - - ::::::{applies-item} ece: - Obtain the endpoint from the **Security** page of the ECE deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters**, and replace its port with `9443`, which is the port used by the remote cluster server interface. - :::::: - - ::::::{applies-item} eck: - Use the FQDN or IP address of the LoadBalancer service, or similar resource, you created to [expose the remote cluster server interface](#enable-rcs). - - If your environment presents the ECK-managed certificates during the TLS handshake, configure the **TLS server name** advanced option as `-es-remote-cluster..svc`. Otherwise, the local cluster cannot establish the connection due to SSL trust errors. - :::::: - - ::::::{applies-item} self: - Use the address of a TCP (layer 4) reverse proxy configured in your environment to route connections to one or more nodes of the cluster on port `9443`. - - If you intend to configure `sniff` mode with a list of {{es}} node addresses as `seeds` , use the [{{es}} API](#using-api) instead. - :::::: - ::::::: + :::{include} _snippets/eck_rcs_external_endpoint_switch.md + ::: Starting with {{kib}} 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. + * **Server name (optional)**: Specify a value if the TLS certificate presented by the remote cluster is signed for a different name than the remote address. 5. Click **Next**. 6. In **Confirm setup**, click **Add remote cluster** (you have already established trust in a previous step). @@ -273,32 +247,12 @@ If you intend to use `sniff` mode, configure it through the [{{es}} API](#using- 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**: The cluster alias must match the one you configured when [adding the API key in the local cluster's keystore](#configure-local-cluster). +* **Remote cluster alias**: The cluster alias must match the `` you configured when [adding the API key in the local cluster's keystore](#configure-local-cluster). * **mode**: Use `proxy` mode in almost all cases. `sniff` mode is only applicable when the remote cluster is self-managed and the local cluster can reach the nodes’ publish addresses directly. * **proxy_address**: Identify the endpoint of the remote cluster, including the hostname, FQDN, or IP address, and the port. Both IPv4 and IPv6 addresses are supported. - :::::::{applies-switch} - - ::::::{applies-item} ess: - Obtain the endpoint from the **Security** page of the ECH deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters** section, and replace its port with `9443`, which is the port used by the remote cluster server interface. - :::::: - - ::::::{applies-item} ece: - Obtain the endpoint from the **Security** page of the ECE deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters**, and replace its port with `9443`, which is the port used by the remote cluster server interface. - :::::: - - ::::::{applies-item} eck: - Use the FQDN or IP address of the LoadBalancer service, or similar resource, you created to [expose the remote cluster server interface](#enable-rcs) on port `9443`. - - If your environment presents the ECK-managed certificates during the TLS handshake, configure the **server_name** field as `-es-remote-cluster..svc`. Otherwise, the local cluster cannot establish the connection due to SSL trust errors. - :::::: - - ::::::{applies-item} self: - The endpoint depends on your network architecture and the selected connection mode (`sniff` or `proxy`). It can be one or more {{es}} nodes, or a TCP (layer 4) load balancer or reverse proxy in front of the cluster, as long as the local cluster can reach them over port `9443`. - - If you are configuring `sniff` mode, set the **seeds** parameter instead of **proxy_address**. Refer to the [connection modes](./connection-modes.md) documentation for details and connectivity requirements of each mode. - :::::: - ::::::: + :::{include} _snippets/eck_rcs_external_endpoint_switch.md + ::: When using an IPv6 address, enclose it in square brackets followed by the port number. For example: `[2001:db8::1]:9443`. From 91b43196bf88e398ecc3b7c8eac4d3eec0366b54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Fri, 5 Dec 2025 18:24:59 +0100 Subject: [PATCH 14/14] Apply suggestions from code review Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> --- .../remote-clusters/_snippets/eck_rcs_intro.md | 2 +- .../remote-clusters/_snippets/self_rcs_enable.md | 10 +++++----- .../eck-remote-clusters-from-external.md | 2 +- .../remote-clusters/eck-remote-clusters-to-external.md | 6 +++--- deploy-manage/remote-clusters/eck-remote-clusters.md | 8 +++++--- 5 files changed, 15 insertions(+), 13 deletions(-) diff --git a/deploy-manage/remote-clusters/_snippets/eck_rcs_intro.md b/deploy-manage/remote-clusters/_snippets/eck_rcs_intro.md index afdbd3f603..7c8be61efe 100644 --- a/deploy-manage/remote-clusters/_snippets/eck_rcs_intro.md +++ b/deploy-manage/remote-clusters/_snippets/eck_rcs_intro.md @@ -1 +1 @@ -The [remote clusters module](/deploy-manage/remote-clusters.md) in {{es}} enables you to establish uni-directional connections to a remote cluster. This functionality is used in cross-cluster replication (CCR) and cross-cluster search (CCS). +The [remote clusters feature](/deploy-manage/remote-clusters.md) in {{es}} enables you to establish uni-directional connections to a remote cluster. This functionality is used in cross-cluster replication (CCR) and cross-cluster search (CCS). diff --git a/deploy-manage/remote-clusters/_snippets/self_rcs_enable.md b/deploy-manage/remote-clusters/_snippets/self_rcs_enable.md index 0dc1e5282d..07aa7414f9 100644 --- a/deploy-manage/remote-clusters/_snippets/self_rcs_enable.md +++ b/deploy-manage/remote-clusters/_snippets/self_rcs_enable.md @@ -4,7 +4,7 @@ 2. Configure the bind and publish address for remote cluster server traffic, for example using [`remote_cluster.host`](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#remote-cluster-network-settings). Without configuring the address, remote cluster traffic can be bound to the local interface, and remote clusters running on other machines can't connect. 3. Optionally, configure the remote server port using [`remote_cluster.port`](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#remote_cluster.port) (defaults to `9443`). -2. Next, generate a certificate authority (CA) and a server certificate/key pair. On one of the nodes of the remote cluster, from the directory where {{es}} has been installed: +2. Generate a certificate authority (CA) and a server certificate/key pair. On one of the nodes of the remote cluster, from the directory where {{es}} has been installed: 1. Create a CA, if you don't have a CA already: @@ -33,12 +33,12 @@ * Use the `--dns` option to specify the relevant DNS name for the certificate. You can specify it multiple times for multiple DNS. * Use the `--ip` option to specify the relevant IP address for the certificate. You can specify it multiple times for multiple IP addresses. - 4. If the remote cluster has multiple nodes, you can either: + 4. If the remote cluster has multiple nodes, you can do one of the following: - * create a single wildcard certificate for all nodes; - * or, create separate certificates for each node either manually or in batch with the [silent mode](elasticsearch://reference/elasticsearch/command-line-tools/certutil.md#certutil-silent). + * Create a single wildcard certificate for all nodes. + * Create separate certificates for each node either manually or in batch with the [silent mode](elasticsearch://reference/elasticsearch/command-line-tools/certutil.md#certutil-silent). -3. On every node of the remote cluster: +3. On every node of the remote cluster, do the following: 1. Copy the `cross-cluster.p12` file from the earlier step to the `config` directory. If you didn't create a wildcard certificate, make sure you copy the correct node-specific p12 file. 2. Add following configuration to [`elasticsearch.yml`](/deploy-manage/stack-settings.md): diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md index ed0462b572..e3f0a92d5a 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters-from-external.md @@ -98,7 +98,7 @@ To allow mutual TLS authentication between the clusters: ``` ::::{note} - Beware of copying the source secret as-is into a different namespace. Check [Common Problems: Owner References](../../troubleshoot/deployments/cloud-on-k8s/common-problems.md#k8s-common-problems-owner-refs) for more information. + Beware of copying the source secret as-is into a different namespace. Refer to [Copying secrets with Owner References](../../troubleshoot/deployments/cloud-on-k8s/common-problems.md#k8s-common-problems-owner-refs) for more information. :::: ::::{note} diff --git a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md index 64a2cf08d2..5982a603a8 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters-to-external.md @@ -14,12 +14,12 @@ sub: These steps describe how to configure a remote cluster connection from an {{es}} cluster managed by {{eck}} (ECK) to an external {{es}} cluster, where external refers to any cluster not managed by the same ECK operator. The remote cluster can be self-managed, part of an {{ech}} (ECH) or {{ece}} (ECE) deployment, or managed by a different ECK operator. -Once the connection is established, you’ll be able to [run CCS queries from {{es}}](/solutions/search/cross-cluster-search.md) or [set up CCR](/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md). +After the connection is established, you’ll be able to [run CCS queries from {{es}}](/solutions/search/cross-cluster-search.md) or [set up CCR](/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md). :::{include} _snippets/terminology.md ::: -In this scenario, most of the configuration must be performed manually, as {{eck}} cannot orchestrate the setup across both clusters. For fully automated configuration between ECK-managed clusters, refer to [Connect to {{es}} clusters in the same ECK environment](./eck-remote-clusters.md). +In this scenario, most of the configuration must be performed manually, as {{eck}} cannot orchestrate the setup across both clusters. For fully automated configuration between ECK-managed clusters, refer to [](./eck-remote-clusters.md). For other remote cluster scenarios with ECK, refer to [Remote clusters on ECK](./eck-remote-clusters-landing.md#eck-rcs-setup). @@ -279,7 +279,7 @@ PUT /_cluster/settings For a full list of available client connection settings, refer to the [remote cluster settings reference](elasticsearch://reference/elasticsearch/configuration-reference/remote-clusters.md). -## Verify remote cluster connection +## Verify the remote cluster connection From the local cluster, check the status of the connection to the remote cluster. If you encounter issues, refer to the [Troubleshooting guide](/troubleshoot/elasticsearch/remote-clusters.md). diff --git a/deploy-manage/remote-clusters/eck-remote-clusters.md b/deploy-manage/remote-clusters/eck-remote-clusters.md index 525a5477b7..8124d871b3 100644 --- a/deploy-manage/remote-clusters/eck-remote-clusters.md +++ b/deploy-manage/remote-clusters/eck-remote-clusters.md @@ -11,7 +11,9 @@ products: # Connect to {{es}} clusters in the same ECK environment [k8s-remote-clusters-connect-internal] -These steps describe how to configure remote clusters between two {{es}} clusters that are managed by the same {{eck}} (ECK) operator. Once that’s done, you’ll be able to [run CCS queries from {{es}}](/solutions/search/cross-cluster-search.md) or [set up CCR](/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md). For other remote cluster scenarios with ECK, refer to [Remote clusters on ECK](./eck-remote-clusters-landing.md). +These steps describe how to configure remote clusters between two {{es}} clusters that are managed by the same {{eck}} (ECK) operator. + +After the connection is established, you’ll be able to [run CCS queries from {{es}}](/solutions/search/cross-cluster-search.md) or [set up CCR](/deploy-manage/tools/cross-cluster-replication/set-up-cross-cluster-replication.md). For other remote cluster scenarios with ECK, refer to [](./eck-remote-clusters-landing.md). ::::{note} The remote clusters feature requires a valid Enterprise license or Enterprise trial license. Check [the license documentation](../license/manage-your-license-in-eck.md) for more details about managing licenses. @@ -20,7 +22,7 @@ The remote clusters feature requires a valid Enterprise license or Enterprise tr ::::{include} _snippets/terminology.md :::: -To create a remote cluster connection to another {{es}} cluster deployed in the same ECK environmnt, specify the `remoteClusters` attribute in your {{es}} spec. +To create a remote cluster connection to another {{es}} cluster deployed in the same ECK environment, specify the `remoteClusters` attribute in your {{es}} spec. ## Security models [k8s_security_models] @@ -83,7 +85,7 @@ spec: 2. The namespace declaration can be omitted if both clusters reside in the same namespace. 3. This example requires the [{{kib}} sample data](/explore-analyze/index.md#gs-get-data-into-kibana). -You can find a complete example in the [recipes directory](https://github.com/elastic/cloud-on-k8s/tree/{{version.eck | M.M}}/config/recipes/remoteclusters). +You can find a complete example in the [{{eck}} repository's recipes directory](https://github.com/elastic/cloud-on-k8s/tree/{{version.eck | M.M}}/config/recipes/remoteclusters). :::::: ::::::{tab-item} TLS certificate (deprecated)