From dfc664c8df904b71a729439d0c78c15f36c2f503 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, 6 Nov 2025 11:43:06 +0100 Subject: [PATCH 1/4] generic changes in snippets and intros --- deploy-manage/remote-clusters.md | 5 ++--- .../remote-clusters/_snippets/allow-connection-intro.md | 6 +++--- deploy-manage/remote-clusters/_snippets/apikeys-intro.md | 8 +------- .../_snippets/apikeys-local-config-intro.md | 2 ++ deploy-manage/remote-clusters/_snippets/terminology.md | 3 +++ deploy-manage/remote-clusters/ec-remote-cluster-ece.md | 3 +++ .../remote-clusters/ec-remote-cluster-other-ess.md | 3 +++ .../remote-clusters/ec-remote-cluster-same-ess.md | 3 +++ .../remote-clusters/ec-remote-cluster-self-managed.md | 5 ++++- .../remote-clusters/ece-remote-cluster-ece-ess.md | 3 +++ .../remote-clusters/ece-remote-cluster-other-ece.md | 3 +++ .../remote-clusters/ece-remote-cluster-same-ece.md | 3 +++ .../remote-clusters/ece-remote-cluster-self-managed.md | 2 ++ 13 files changed, 35 insertions(+), 14 deletions(-) create mode 100644 deploy-manage/remote-clusters/_snippets/terminology.md diff --git a/deploy-manage/remote-clusters.md b/deploy-manage/remote-clusters.md index 4439dfc311..6e6cf200ca 100644 --- a/deploy-manage/remote-clusters.md +++ b/deploy-manage/remote-clusters.md @@ -20,9 +20,8 @@ Remote clusters are especially useful in two cases: - **Cross-cluster search** [Cross-cluster search](/solutions/search/cross-cluster-search.md), or CCS, enables you to run a search request against one or more remote clusters. This capability provides each region with a global view of all clusters, allowing you to send a search request from a local cluster and return results from all connected remote clusters. For full {{ccs}} capabilities, the local and remote cluster must be on the same [subscription level](https://www.elastic.co/subscriptions). -::::{note} about terminology -In the case of remote clusters, the {{es}} cluster or deployment initiating the connection and requests is often referred to as the **local cluster**, while the {{es}} cluster or deployment receiving the requests is referred to as the **remote cluster**. -:::: +:::{include} ./remote-clusters/_snippets/terminology.md +::: ## Security models and connection modes diff --git a/deploy-manage/remote-clusters/_snippets/allow-connection-intro.md b/deploy-manage/remote-clusters/_snippets/allow-connection-intro.md index 8afbdba98b..da742d70f0 100644 --- a/deploy-manage/remote-clusters/_snippets/allow-connection-intro.md +++ b/deploy-manage/remote-clusters/_snippets/allow-connection-intro.md @@ -1,7 +1,7 @@ -Before you start, consider the security model that you would prefer to use for authenticating remote connections between clusters, and follow the corresponding steps. +Before you start, consider the [security model](/deploy-manage/remote-clusters/security-models.md) that you would prefer to use for authenticating remote connections between clusters, and follow the corresponding steps. API key -: For deployments based on {{stack}} 8.14 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model offers administrators of both the local and the remote deployment fine-grained access controls. +: For deployments based on {{stack}} 8.14 or later, you can use an API key to authenticate and authorize cross-cluster operations to a remote cluster. This model uses a dedicated service endpoint, on port `9443` by default, and gives administrators fine-grained control over remote access. The API key is created on the remote cluster and defines the permissions available to all cross-cluster requests, while local user roles can further restrict, but not extend, those permissions. TLS certificate (deprecated in {{stack}} 9.0.0) -: This model uses mutual TLS authentication for cross-cluster operations. User authentication is performed on the local cluster and a user's role names are passed to the remote cluster. A superuser on the local deployment gains total read access to the remote deployment, so it is only suitable for deployments that are in the same security domain. +: This model uses mutual TLS authentication over the {{es}} transport interface for cross-cluster operations. User authentication is performed on the local cluster and a user's role names are passed to the remote cluster for authorization. Because a superuser on the local cluster automatically gains full read access to the remote cluster, this model is only suitable for clusters within the same security domain. diff --git a/deploy-manage/remote-clusters/_snippets/apikeys-intro.md b/deploy-manage/remote-clusters/_snippets/apikeys-intro.md index a251de7a56..5e0184b5ac 100644 --- a/deploy-manage/remote-clusters/_snippets/apikeys-intro.md +++ b/deploy-manage/remote-clusters/_snippets/apikeys-intro.md @@ -1,7 +1 @@ -API key authentication enables a local cluster to authenticate itself with a remote cluster via a [cross-cluster API key](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-cross-cluster-api-key). The API key needs to be created by an administrator of the remote cluster. The local cluster is configured to provide this API key on each request to the remote cluster. The remote cluster verifies the API key and grants access, based on the API key’s privileges. - -All cross-cluster requests from the local cluster are bound by the API key’s privileges, regardless of local users associated with the requests. For example, if the API key only allows read access to `my-index` on the remote cluster, even a superuser from the local cluster is limited by this constraint. This mechanism enables the remote cluster’s administrator to have full control over who can access what data with cross-cluster search and/or cross-cluster replication. The remote cluster’s administrator can be confident that no access is possible beyond what is explicitly assigned to the API key. - -On the local cluster side, not every local user needs to access every piece of data allowed by the API key. An administrator of the local cluster can further configure additional permission constraints on local users so each user only gets access to the necessary remote data. Note it is only possible to further reduce the permissions allowed by the API key for individual local users. It is impossible to increase the permissions to go beyond what is allowed by the API key. - -If you run into any issues, refer to [Troubleshooting](/troubleshoot/elasticsearch/remote-clusters.md). +Follow these steps to configure the [API key security model](/deploy-manage/remote-clusters/security-models.md#api-key) for remote clusters. If you run into any issues, refer to [Troubleshooting](/troubleshoot/elasticsearch/remote-clusters.md). 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..73d0e44c29 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,3 @@ 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. + +Additionally, if the remote cluster server uses a certificate signed by a private certificate authority (CA), you must add the CA to the local deployment configuration so that it can trust the remote server. \ No newline at end of file diff --git a/deploy-manage/remote-clusters/_snippets/terminology.md b/deploy-manage/remote-clusters/_snippets/terminology.md new file mode 100644 index 0000000000..e428412656 --- /dev/null +++ b/deploy-manage/remote-clusters/_snippets/terminology.md @@ -0,0 +1,3 @@ +::::{admonition} Note about terminology +In the case of remote clusters, the {{es}} cluster or deployment initiating the connection and requests is often referred to as the **local cluster**, while the {{es}} cluster or deployment receiving the requests is referred to as the **remote cluster**. +:::: diff --git a/deploy-manage/remote-clusters/ec-remote-cluster-ece.md b/deploy-manage/remote-clusters/ec-remote-cluster-ece.md index 476ce601e9..7faa643d71 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-ece.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-ece.md @@ -16,6 +16,9 @@ sub: This section explains how to configure a deployment to connect remotely to clusters belonging to an {{ECE}} (ECE) environment. +:::{include} _snippets/terminology.md +::: + ::::{note} If network security filters are applied to the remote cluster on ECE, the remote cluster administrator must configure an [IP filter](/deploy-manage/security/ip-filtering-ece.md) to allow traffic from [{{ecloud}} IP addresses](/deploy-manage/security/elastic-cloud-static-ips.md#ec-egress). For more information, refer to [Remote clusters and network security](/deploy-manage/remote-clusters.md#network-security). :::: 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 0c815ff348..eab530c07c 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md @@ -15,6 +15,9 @@ sub: This section explains how to configure a deployment to connect remotely to clusters belonging to a different {{ecloud}} organization. +:::{include} _snippets/terminology.md +::: + ::::{note} If network security policies are applied to the remote cluster, the remote cluster administrator must configure a [private connection policy of type remote cluster](/deploy-manage/security/remote-cluster-filtering.md), using either the organization ID or the Elasticsearch cluster ID of the local cluster as the filtering criteria. For more information, refer to [Remote clusters and network security](/deploy-manage/remote-clusters.md#network-security). :::: 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 d9c838abca..0fe3032daa 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md @@ -15,6 +15,9 @@ sub: This section explains how to configure a deployment to connect remotely to clusters belonging to the same {{ecloud}} organization. +:::{include} _snippets/terminology.md +::: + ::::{note} If network security policies are applied to the remote cluster, the remote cluster administrator must configure a [private connection policy of type remote cluster](/deploy-manage/security/remote-cluster-filtering.md), using either the organization ID or the Elasticsearch cluster ID of the local cluster as the filtering criteria. For more information, refer to [Remote clusters and network security](/deploy-manage/remote-clusters.md#network-security). :::: 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 55dba71592..cd8474e6c3 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md @@ -14,6 +14,9 @@ products: This section explains how to configure a deployment to connect remotely to self-managed clusters. +:::{include} _snippets/terminology.md +::: + ## Allow the remote connection [ec_allow_the_remote_connection_4] :::{include} _snippets/allow-connection-intro.md @@ -43,7 +46,7 @@ This section explains how to configure a deployment to connect remotely to self- :::{include} _snippets/apikeys-local-config-intro.md ::: -The steps to follow depend on whether the Certificate Authority (CA) of the remote environment’s {{es}} HTTPS server, proxy or, load balancing infrastructure is public or private. +The steps to follow depend on whether the Certificate Authority (CA) of the remote environment’s {{es}} remote cluster server, proxy or, load balancing infrastructure is public or private. ::::{dropdown} The CA is public 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 3ff8e83f6a..4c7b2a8f34 100644 --- a/deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md +++ b/deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md @@ -16,6 +16,9 @@ sub: This section explains how to configure an {{ece}} (ECE) deployment to connect remotely to clusters belonging to an {{ecloud}} organization. +:::{include} _snippets/terminology.md +::: + ::::{note} If network security filters are applied to the remote cluster on {{ecloud}}, the remote cluster administrator must configure an [IP filter](/deploy-manage/security/ip-filtering-cloud.md) to allow connections from the IP addresses (or CIDR ranges) of the local ECE allocator hosts. For more information, refer to [Remote clusters and network security](/deploy-manage/remote-clusters.md#network-security). :::: 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 6acac7e01c..7690d27981 100644 --- a/deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md +++ b/deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md @@ -15,6 +15,9 @@ sub: This section explains how to configure a deployment to connect remotely to clusters belonging to a different {{ece}} environment. +:::{include} _snippets/terminology.md +::: + ::::{note} If network security filters are applied to the remote cluster on ECE, the remote cluster administrator must configure an [IP filter](/deploy-manage/security/ip-filtering-ece.md) to allow connections from the IP addresses (or CIDR ranges) of the local ECE allocator hosts. For more information, refer to [Remote clusters and network security](/deploy-manage/remote-clusters.md#network-security). :::: 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 4b3e01c7b9..b6ad34ef82 100644 --- a/deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md +++ b/deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md @@ -15,6 +15,9 @@ sub: This section explains how to configure a deployment to connect remotely to clusters belonging to the same {{ece}} environment. +:::{include} _snippets/terminology.md +::: + ::::{note} If network security filters are applied to the remote cluster, the remote cluster administrator must configure a [remote cluster filter](/deploy-manage/security/remote-cluster-filtering.md), using either the ECE environment ID or the Elasticsearch cluster ID of the local cluster as the filtering criteria. For more information, refer to [Remote clusters and network security](/deploy-manage/remote-clusters.md#network-security). :::: 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 401c0fa104..93f91ae9b3 100644 --- a/deploy-manage/remote-clusters/ece-remote-cluster-self-managed.md +++ b/deploy-manage/remote-clusters/ece-remote-cluster-self-managed.md @@ -14,6 +14,8 @@ products: This section explains how to configure a deployment to connect remotely to self-managed clusters. +:::{include} _snippets/terminology.md +::: ## Allow the remote connection [ece_allow_the_remote_connection_4] From fb7228a290c0be7de971fc8e9939516357632d32 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, 6 Nov 2025 13:01:39 +0100 Subject: [PATCH 2/4] Update deploy-manage/remote-clusters/_snippets/apikeys-local-config-intro.md --- .../remote-clusters/_snippets/apikeys-local-config-intro.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) 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 73d0e44c29..9bc80b0ede 100644 --- a/deploy-manage/remote-clusters/_snippets/apikeys-local-config-intro.md +++ b/deploy-manage/remote-clusters/_snippets/apikeys-local-config-intro.md @@ -1,3 +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. - -Additionally, if the remote cluster server uses a certificate signed by a private certificate authority (CA), you must add the CA to the local deployment configuration so that it can trust the remote server. \ No newline at end of file +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. \ No newline at end of file From e832b25c9442b59d41f205d744a04c8df0ccb80e 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, 6 Nov 2025 13:04:57 +0100 Subject: [PATCH 3/4] Fix missing newline at end of apikeys-local-config-intro.md --- .../remote-clusters/_snippets/apikeys-local-config-intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 9bc80b0ede..5611e1ee12 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. \ No newline at end of file +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. From ae3c491b7c96e8906da890ae03f6d39eb25e3cfe 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, 6 Nov 2025 20:59:15 +0100 Subject: [PATCH 4/4] Update deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md Co-authored-by: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> --- deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 cd8474e6c3..00e186f4d0 100644 --- a/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md +++ b/deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md @@ -46,7 +46,7 @@ This section explains how to configure a deployment to connect remotely to self- :::{include} _snippets/apikeys-local-config-intro.md ::: -The steps to follow depend on whether the Certificate Authority (CA) of the remote environment’s {{es}} remote cluster server, proxy or, load balancing infrastructure is public or private. +The steps to follow depend on whether the Certificate Authority (CA) of the remote environment’s {{es}} remote cluster server, proxy, or load balancing infrastructure is public or private. ::::{dropdown} The CA is public