Remote clusters - private CA connections and trusted environments management converted to snippets (#3841)

## Summary

This PR converts duplicate content into reusable snippets for remote
cluster configuration, specifically for private CA connections and
trusted environment management, plus some small refinement.

**Note**: The content of `retrieve-ece-ca.md` would benefit from a
writing review, as it's the only piece of text that was elaborated for
this PR, the rest is internal refactoring and minor refinement.

## Changes

### Private CA Certificate Retrieval
- Created `retrieve-ece-ca.md` snippet containing the steps to retrieve
the CA certificate of a remote ECE proxy
- Created `apikeys-local-ece-remote-private.md` snippet with the steps
to configure the local ECE deployment when the remote cluster
certificate is signed by a private CA
- Created `apikeys-local-ech-remote-private.md` snippet with the steps
to configure the local {{ech}} deployment when the remote cluster
certificate is signed by a private CA
- Replaced duplicate content in all affected files with snippet includes

### Trusted Environment Management
- Converted the following pages to use shared snippets as they were 99%
identical:
  - `ec-edit-remove-trusted-environment.md`
  - `ece-edit-remove-trusted-environment.md`
- Created snippets:
  - `trusted-environment-manage.md` - Introduction section
- `trusted-environment-remove-cert.md` - Remove certificate-based
trusted environment steps
- `trusted-environment-update-cert.md` - Update certificate-based
trusted environment steps
- `trusted-environment-change-api-key.md` - Change cross-cluster API key
steps

### Additional Improvements
- Removed duplicate image files
(`cloud-enterprise-delete-trust-environment.png` and
`cloud-enterprise-edit-trust-environment.png`) that were identical to
their non-enterprise counterparts
- Updated image references to use the unified image names

### Minor Updates
- Applied small changes to other snippets that will be used later with
incoming ECK-related documentation for remote clusters

---------

Co-authored-by: Vlada Chirmicci <[email protected]>

Author: eedugon

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

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

@@ -18,7 +18,7 @@ It requires remote_type substitution to be defined
 
       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**: 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.
+    * **Remote 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.
 
       ::::{note}
       If you’re using API keys as security model, change the port to `9443`.
@@ -27,7 +27,7 @@ It requires remote_type substitution to be defined
     * **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.
 
-        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.
+        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.
 
       * **Socket connections**: Define the number of connections to open with the remote cluster.
 

deploy-manage/remote-clusters/_snippets/retrieve-ece-ca.md

@@ -0,0 +1,14 @@
+Before configuring the local deployment, retrieve the CA certificate of the remote ECE proxy. To find this certificate:
+
+1. In the remote ECE environment, go to **Platform > Settings > TLS certificates**.
+2. Select **Show certificate chain** under **Proxy**.
+3. Click **Copy root certificate** and paste it into a new file. The root certificate is the last certificate shown in the chain.
+
+    :::{image} /deploy-manage/images/cloud-remote-clusters-proxy-certificate.png
+    :alt: Certificate to copy from the chain
+    :::
+
+4. Save the file as `.crt`.
+
+You can now proceed to configure the local deployment. The CA file you saved will be used in one of the following steps.
+

deploy-manage/remote-clusters/_snippets/trusted-environment-change-api-key.md

@@ -0,0 +1,27 @@
+This section describes the steps to change the API key used for an existing remote connection. For example, if the previous key expired and you need to rotate it with a new one.
+
+::::{note}
+If you need to update the permissions granted by a cross-cluster API key for a remote connection, you only need to update the privileges granted by the API key directly in {{kib}}.
+::::
+
+
+1. 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 with the appropriate permissions. Configure it with 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. You will need it in the next steps.
+3. From the navigation menu of your local deployment, select **Security** and locate the **Remote connections** section.
+4. Locate the API key currently used for connecting to the remote cluster, copy its current alias, and delete it.
+5. Add the new API key by selecting **Add API key**.
+
+    * For the **Remote cluster name**, enter the same alias that was used for the previous key.
+
+      ::::{note}
+      If you use a different alias, you also need to re-create the remote cluster in {{kib}} with a **Remote cluster name** that matches the new alias.
+      ::::
+
+    * For the **Cross-cluster API key**, paste the encoded cross-cluster API key, then click **Add** to save the API key to the keystore.
+
+6. 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>
+
+   ::::{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.
+   ::::
+