Remote clusters: generic changes in snippets and intros (#3835)

This PR introduces some improvements that I'd like to merge before the
major updates to ECK docs around remote clusters.

Main changes:
- Terminology snippet added in the main ECE --> xx and ECH --> xx remote
clusters docs.
- Improved the API Key and TLS certificates introduction and link to the
new document about Security models created recently.
- Removed the big text that we had in the steps for API key, as that's
now better covered in the intro and in the referenced doc.

---------

Co-authored-by: David Kilfoyle <[email protected]>

Author: eedugon

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
 

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.

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).

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**.
+::::

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).
 ::::

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).
 ::::

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).
 ::::

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
 

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).
 ::::

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).
 ::::