Merge branch 'main' into align-sec-landings-part2

Author: jmikell821

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/apikeys-local-ece-remote-private.md

@@ -0,0 +1,37 @@
+<!--
+This snippet is in use in the following locations:
+- ece-remote-cluster-self-managed.md
+- ece-remote-cluster-other-ece.md
+
+It requires remote_type substitution to be defined
+-->
+1. [Log in to the Cloud UI](/deploy-manage/deploy/cloud-enterprise/log-into-cloud-ui.md).
+2. On the **Deployments** page, select your deployment.
+
+    Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters.
+
+3. Access the **Security** page of the deployment.
+4. Select **Remote Connections > Add trusted environment** and choose **{{remote_type}}**. Then click **Next**.
+5. Select **API keys** as authentication mechanism and click **Next**.
+6. When asked whether the Certificate Authority (CA) of the remote environment’s proxy or load-balancing infrastructure is public, select **No, it is private**.
+7. Add the API key:
+
+    1. Fill both fields.
+
+        * For the **Remote cluster name**, enter the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores.
+        * For the **Cross-cluster API key**, paste the encoded cross-cluster API key.
+
+    2. Click **Add** to save the API key to the keystore.
+    3. Repeat these steps for each API key you want to add. For example, if you want to use several clusters of the remote environment for CCR or CCS.
+
+8. Add the CA certificate of the remote environment.
+9. Provide a name for the trusted environment. That name will appear in the trust summary of your deployment's **Security** page.
+10. Select **Create trust** to complete the configuration.
+11. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment's main page, locate the **Actions** menu, and select **Restart {{es}}**.
+
+    ::::{note}
+    If the local deployment runs on version 8.14 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys.
+    ::::
+
+If you need to update the remote connection with different permissions later, refer to [Change a cross-cluster API key used for a remote connection](/deploy-manage/remote-clusters/ece-edit-remove-trusted-environment.md#edit-remove-trusted-environment-api-key).
+

deploy-manage/remote-clusters/_snippets/apikeys-local-ece-remote-public.md

@@ -1,3 +1,10 @@
+<!--
+This snippet is in use in the following locations:
+- ece-remote-cluster-self-managed.md
+- ece-remote-cluster-same-ece.md
+- ece-remote-cluster-other-ece.md
+- ece-remote-cluster-ece-ess.md
+-->
 1. [Log into the Cloud UI](/deploy-manage/deploy/cloud-enterprise/log-into-cloud-ui.md).
 2. On the **Deployments** page, select your deployment.
 
@@ -13,11 +20,10 @@
 
     2. Click **Add** to save the API key to the keystore.
 
-5. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment's main page (named after your deployment's name), locate the **Actions** menu, and select **Restart {{es}}**.<br>
+5. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment's main page (named after your deployment's name), locate the **Actions** menu, and select **Restart {{es}}**.
 
     ::::{note}
     If the local deployment runs on version 8.14 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys.
     ::::
 
-
-If you need to update the remote connection with different permissions later, refer to [Change a cross-cluster API key used for a remote connection](/deploy-manage/remote-clusters/ece-edit-remove-trusted-environment.md#ece-edit-remove-trusted-environment-api-key).
+If you need to update the remote connection with different permissions later, refer to [Change a cross-cluster API key used for a remote connection](/deploy-manage/remote-clusters/ece-edit-remove-trusted-environment.md#edit-remove-trusted-environment-api-key).

deploy-manage/remote-clusters/_snippets/apikeys-local-ech-remote-private.md

@@ -0,0 +1,36 @@
+<!--
+This snippet is in use in the following locations:
+- ec-remote-cluster-self-managed.md
+- ec-remote-cluster-ece.md
+
+It requires remote_type substitution to be defined
+-->
+1. Log in to the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body).
+2. On the home page, find your hosted deployment and select **Manage** to access it directly. Or, select **Hosted deployments** to go to the **Hosted deployments** page to view all of your deployments.
+
+    On the **Hosted deployments** page you can narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list.
+
+3. From the navigation menu, select **Security**.
+4. Select **Remote Connections > Add trusted environment** and choose **{{remote_type}}**. Then click **Next**.
+5. Select **API keys** as authentication mechanism and click **Next**.
+6. When asked whether the Certificate Authority (CA) of the remote environment’s proxy or load-balancing infrastructure is public, select **No, it is private**.
+7. Add the API key:
+
+    1. Fill both fields.
+
+        * For the **Remote cluster name**, enter the alias of your choice. You will use this alias to connect to the remote cluster later. It must be lowercase and only contain letters, numbers, dashes and underscores.
+        * For the **Cross-cluster API key**, paste the encoded cross-cluster API key.
+
+    2. Click **Add** to save the API key to the keystore.
+    3. Repeat these steps for each API key you want to add. For example, if you want to use several clusters of the remote environment for CCR or CCS.
+
+8. Add the CA certificate of the remote environment.
+9. Provide a name for the trusted environment. That name will appear in the trust summary of your deployment's **Security** page.
+10. Select **Create trust** to complete the configuration.
+11. Restart the local deployment to reload the keystore with its new setting. To do that, go to the deployment's main page, locate the **Actions** menu, and select **Restart {{es}}**.
+
+    ::::{note}
+    If the local deployment runs on version 8.14 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys.
+    ::::
+
+If you need to update the remote connection with different permissions later, refer to [Change a cross-cluster API key used for a remote connection](/deploy-manage/remote-clusters/ec-edit-remove-trusted-environment.md#edit-remove-trusted-environment-api-key).

deploy-manage/remote-clusters/_snippets/apikeys-local-ech-remote-public.md

@@ -1,3 +1,10 @@
+<!--
+This snippet is in use in the following locations:
+- ec-remote-cluster-self-managed.md
+- ec-remote-cluster-same-ess.md
+- ec-remote-cluster-other-ess.md
+- ec-remote-cluster-ece.md
+-->
 1. Log in to the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body).
 2. On the home page, find your hosted deployment and select **Manage** to access it directly. Or, select **Hosted deployments** to go to the **Hosted deployments** page to view all of your deployments.
 
@@ -13,11 +20,10 @@
 
     2. Click **Add** to save the API key.
 
-5. Restart the local deployment to reload the new setting. To do that, go to the deployment's main page (named after your deployment's name), locate the **Actions** menu, and select **Restart {{es}}**.<br>
+5. Restart the local deployment to reload the new setting. To do that, go to the deployment's main page (named after your deployment's name), locate the **Actions** menu, and select **Restart {{es}}**.
 
     ::::{note}
     If the local deployment runs on version 8.14 or greater, you no longer need to perform this step because the keystore is reloaded automatically with the new API keys.
     ::::
 
-
-If you need to update the remote connection with different permissions later, refer to [Change a cross-cluster API key used for a remote connection](/deploy-manage/remote-clusters/ec-edit-remove-trusted-environment.md#ec-edit-remove-trusted-environment-api-key).
+If you need to update the remote connection with different permissions later, refer to [Change a cross-cluster API key used for a remote connection](/deploy-manage/remote-clusters/ec-edit-remove-trusted-environment.md#edit-remove-trusted-environment-api-key).

deploy-manage/remote-clusters/_snippets/rcs-elasticsearch-api-snippet-self.md

@@ -3,11 +3,11 @@ This snippet is in use in the following locations:
 - ece-remote-cluster-self-managed.md
 - ec-remote-cluster-self-managed.md
 -->
-To configure a self-managed cluster as 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:
+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**.
 * `mode`: `proxy`
-* `proxy_address`: Enter the endpoint of the remote self-managed cluster, including the hostname, FQDN, or IP address, and the port. Both IPv4 and IPv6 addresses are supported.
+* `proxy_address`: Enter the endpoint of the remote cluster, including the hostname, FQDN, or IP address, and the port. Both IPv4 and IPv6 addresses are supported.
 
   Make sure you use the correct port for your authentication method:
   * **API keys**: Use the port configured in the remote cluster interface of the remote cluster (defaults to `9443`).  

deploy-manage/remote-clusters/_snippets/rcs-elasticsearch-api-snippet.md

@@ -13,15 +13,15 @@ To configure a deployment as a remote cluster, use the [cluster update settings
 
 * `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**.
 * `mode`: `proxy`
-* `proxy_address`: This value can be found on the **Security** page of the {{remote_type}} you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters** section. 
+* `proxy_address`: This value can be found on the **Security** page of the {{remote_type}} deployment you want to use as a remote. Copy the **Proxy address** from the **Remote cluster parameters** section.
 
    Using the API, this value can be obtained from the {{es}} resource info, concatenating the field `metadata.endpoint` and port `9400` using a semicolon.
 
   ::::{note}
   If you’re using API keys as security model, change the port to `9443`.
   ::::
 
-* `server_name`: This value can be found on the **Security** page of the {{remote_type}} you want to use as a remote. Copy the **Server name** from the **Remote cluster parameters** section. 
+* `server_name`: This value can be found on the **Security** page of the {{remote_type}} deployment you want to use as a remote. Copy the **Server name** from the **Remote cluster parameters** section.
 
    Using the API, this can be obtained from the {{es}} resource info field `metadata.endpoint`.
 

deploy-manage/remote-clusters/_snippets/rcs-kibana-api-snippet-self.md

@@ -12,7 +12,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.
-    * **Remote address**: Enter the endpoint of the remote self-managed cluster, including the hostname, FQDN, or IP address, and the port.
+    * **Remote address**: Enter the endpoint of the remote cluster, including the hostname, FQDN, or IP address, and the port.
 
       Make sure you use the correct port for your authentication method:
       * **API keys**: Use the port configured in the remote cluster interface of the remote cluster (defaults to `9443`).