ECE and ECH to ECK remote clusters setup updated for API keys

eedugon · eedugon · commit ee287be7917f · 2025-11-07T14:25:18.000+01:00
diff --git a/deploy-manage/remote-clusters/_snippets/apikeys-local-ece-remote-private.md b/deploy-manage/remote-clusters/_snippets/apikeys-local-ece-remote-private.md
@@ -10,7 +10,7 @@ It requires remote_type substitution to be defined
 
     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.
+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**.
@@ -21,13 +21,13 @@ It requires remote_type substitution to be defined
         * 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.
+    2. Click **Add** to save the API key.
     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}}**.
+11. Restart the local deployment to reload the 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.
diff --git a/deploy-manage/remote-clusters/_snippets/apikeys-local-ece-remote-public.md b/deploy-manage/remote-clusters/_snippets/apikeys-local-ece-remote-public.md
@@ -10,17 +10,17 @@ This snippet is in use in the following locations:
 
     Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters.
 
-3. From the deployment menu, select **Security**.
+3. From the navigation menu, select **Security**.
 4. Locate **Remote Connections > Trust management > Connections using API keys** and select **Add API key**.
 
     1. Fill both fields.
 
-        * For the **Remote cluster name**, enter the 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 **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.
+    2. Click **Add** to save the API key.
 
-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}}**.
+5. Restart the local deployment to reload the 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.
diff --git a/deploy-manage/remote-clusters/_snippets/apikeys-local-ech-remote-private.md b/deploy-manage/remote-clusters/_snippets/apikeys-local-ech-remote-private.md
@@ -21,13 +21,13 @@ It requires remote_type substitution to be defined
         * 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.
+    2. Click **Add** to save the API key.
     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}}**.
+11. Restart the local deployment to reload the 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.
diff --git a/deploy-manage/remote-clusters/_snippets/apikeys-local-ech-remote-public.md b/deploy-manage/remote-clusters/_snippets/apikeys-local-ech-remote-public.md
@@ -15,12 +15,12 @@ This snippet is in use in the following locations:
 
     1. Fill both fields.
 
-        * For the **Remote cluster name**, enter the 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 **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.
 
-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}}**.
+5. Restart the local deployment to reload the 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.
diff --git a/deploy-manage/remote-clusters/_snippets/eck_expose_transport.md b/deploy-manage/remote-clusters/_snippets/eck_expose_transport.md
@@ -0,0 +1,15 @@
+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: <cluster-name>
+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 `<cluster-name>-es-transport` through one of the Kubernetes Ingress controllers that support TCP services.
diff --git a/deploy-manage/remote-clusters/_snippets/eck_rcs_connect_intro.md b/deploy-manage/remote-clusters/_snippets/eck_rcs_connect_intro.md
@@ -0,0 +1,10 @@
+On the local deployment, add the remote ECK cluster using {{kib}} or the {{es}} API.
+
+::::{note}
+When configuring the remote cluster connection:
+
+* **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 authentication) or the transport interface (for certificate-based authentication).
+
+* **TLS server name**: You can try leaving this field empty first. If the connection fails, and your environment is presenting the ECK-managed certificates during the TLS handshake, use `<cluster-name>-es-remote-cluster.<namespace>.svc` as the server name. For example, for a cluster named `quickstart` in the `default` namespace, use `quickstart-es-remote-cluster.default.svc`.
+::::
+
diff --git a/deploy-manage/remote-clusters/_snippets/eck_rcs_enable.md b/deploy-manage/remote-clusters/_snippets/eck_rcs_enable.md
@@ -0,0 +1,23 @@
+By default, the remote cluster server interface is disabled 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:
+
+```yaml subs=true
+apiVersion: elasticsearch.k8s.elastic.co/v1
+kind: Elasticsearch
+metadata:
+  name: <cluster-name>
+  namespace: <namespace>
+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.
+::::
+
diff --git a/deploy-manage/remote-clusters/_snippets/eck_rcs_expose.md b/deploy-manage/remote-clusters/_snippets/eck_rcs_expose.md
@@ -0,0 +1,36 @@
+When the remote cluster server is enabled, ECK automatically creates a Kubernetes service named `<cluster-name>-es-remote-cluster` that exposes the server internally on port `9443`:
+
+```sh
+quickstart-es-remote-cluster       ClusterIP      None             <none>         9443/TCP            4h13m
+```
+
+To allow other clusters running outside your Kubernetes environment to connect, you must expose this service externally. As of ECK {{version.eck}}, you cannot customize the service that ECK generates for the remote cluster interface, but you can create your own `LoadBalancer` service, `Ingress` object, or use another method available in your environment.
+
+For example, the following command creates a service named `quickstart-es-remote-cluster-lb`, similar to the managed `quickstart-es-remote-cluster` but of type `LoadBalancer`.
+
+```sh
+kubectl expose service quickstart-es-remote-cluster \
+  --name=quickstart-es-remote-cluster-lb \
+  --type=LoadBalancer \ <1>
+  --port=9443 --target-port=9443
+```
+
+1. On cloud providers which support external load balancers, setting the type to LoadBalancer provisions a load balancer for your service. Alternatively, expose the service `<cluster-name>-es-remote-cluster` through one of the Kubernetes Ingress controllers that support TCP services.
+
+
+:::{admonition} About exposing the service and TLS certificates
+When exposing the remote cluster service, determine which TLS certificate will be presented to clients and whether a certificate authority (CA) is required to establish trust. This depends on how traffic to port `9443` is routed in your environment and which component terminates the TLS connection:
+
+* **{{es}} TLS termination**
+
+  If the connection reaches the {{es}} Pods without intermediate TLS termination, the {{es}} nodes present their transport certificates managed by ECK. The local cluster must therefore trust these certificates by including the ECK-managed transport CA, which you can retrieve in the next section.
+
+  This setup is typical when using standard `LoadBalancer` services provided by most cloud providers.
+
+* **External TLS termination**
+
+  If the connection to port `9443` of your {{es}} cluster is handled by an external load balancer, Ingress controller, or another proxy that performs SSL termination with its own certificates, use the CA associated with that component if it's signed by a private CA.
+  
+  If the external TLS termination uses a publicly trusted certificate, no additional CA is needed.
+:::
+
diff --git a/deploy-manage/remote-clusters/_snippets/eck_rcs_retrieve_ca.md b/deploy-manage/remote-clusters/_snippets/eck_rcs_retrieve_ca.md
@@ -0,0 +1,23 @@
+The certificate authority (CA) used by ECK to issue certificates for the remote cluster server interface is stored in the `ca.crt` key of the secret named `<cluster_name>-es-transport-certs-public`.
+
+If the external connections reach the {{es}} Pods on port `9443` without any intermediate TLS termination, you must retrieve this CA, as it will be required in the local cluster configuration to establish trust.
+
+For example, to save the transport CA certificate of a cluster named `quickstart` into a local file, run:
+
+```sh
+kubectl get secret quickstart-es-transport-certs-public \
+-o go-template='{{index .data "ca.crt" | base64decode}}' > eck_transport_ca.crt
+```
+
+You can verify that the file contains a valid CA certificate by running:
+
+```bash
+openssl x509 -in eck_transport_ca.crt -noout -text
+```
+
+::::{important}
+ECK-managed CA certificates are automatically rotated after one year by default, but you can [configure](/deploy-manage/deploy/cloud-on-k8s/configure-eck.md) a different validity period.
+
+Ensure that this CA is updated in all environments where it's used after rotation to preserve trust.
+::::
+
diff --git a/deploy-manage/remote-clusters/ec-enable-ccs-for-eck.md b/deploy-manage/remote-clusters/ec-enable-ccs-for-eck.md
@@ -8,20 +8,87 @@ applies_to:
     eck: ga
 products:
   - id: cloud-hosted
+sub:
+  remote_type: Self-managed
 ---
 
 # Connect {{ech}} deployments to {{eck}} clusters [ec-enable-ccs-for-eck]
 
 These steps describe how to configure remote clusters between an {{es}} cluster in {{ech}} (ECH) and an {{es}} cluster running within [{{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
+:::
 
-## Establish trust between the two clusters [ec_establish_trust_between_two_clusters]
 
-The first step is to establish trust between the two clusters, by adding the CA certificate and trust details of each environment into the other.
+## Allow the remote connection [ec_allow_the_remote_connection_4]
 
-This guide uses TLS certificates to secure remote cluster connections and follows a similar approach to [Access clusters of a self-managed environment](ec-remote-cluster-self-managed.md).
+:::{include} _snippets/allow-connection-intro.md
+:::
 
-### Establish trust in the ECH cluster [ec_establish_trust_in_the_elasticsearch_service_cluster]
+:::::::{tab-set}
+
+::::::{tab-item} API key
+
+:::{include} _snippets/apikeys-intro.md
+:::
+
+### Prerequisites and limitations [ec_prerequisites_and_limitations_4]
+
+:::{include} _snippets/apikeys-prerequisites-limitations.md
+:::
+
+### 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
+
+:::{include} _snippets/apikeys-local-ech-remote-public.md
+:::
+
+::::
+
+::::{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.
+
+:::{include} _snippets/apikeys-local-ech-remote-private.md
+:::
+::::
+
+::::::
+
+::::::{tab-item} TLS certificate (deprecated)
+### Establish mutual trust between the clusters [ec_establish_trust_between_two_clusters]
+
+When using TLS certificates-based authentication, the first step is to establish trust between the two clusters, by adding the CA certificate and trust details of each environment into the other.
+
+#### Establish trust in the ECH cluster [ec_establish_trust_in_the_elasticsearch_service_cluster]
 
 To configure trust in the ECH deployment:
 
@@ -52,7 +119,7 @@ To configure trust in the ECH deployment:
 
     7. On the confirmation screen, when prompted **Have you already set up trust from the other environment?**, select **No, I have NOT set up trust from the other environment yet**. Download both the ECH deployment CA certificate and the `trust.yml` file. These files can also be retrieved from the **Security** page of the deployment. You’ll use these files to configure trust in the ECK deployment.
 
-### Update the downloaded `trust.yml` file for ECK compatibility
+#### Update the downloaded `trust.yml` file for ECK compatibility
 
 The `trust.yml` file you downloaded from the Cloud UI includes a subject name pattern that isn't valid for your ECK cluster. Before using it in your ECK cluster, you need to update the file with the pattern that matches your cluster.
 
@@ -92,8 +159,7 @@ trust.subject_name:
 
 Apply the changes and save the `trust.yml` file.
 
-
-### Establish trust in the ECK cluster [ec_establish_trust_in_the_eck_cluster]
+#### Establish trust in the ECK cluster [ec_establish_trust_in_the_eck_cluster]
 
 To configure trust in the ECK deployment:
 
@@ -142,14 +208,30 @@ To configure trust in the ECK deployment:
     1. Ensure `secretName` matches the name of the Secret you created earlier.
     2. Ensure `name` matches the name of the ConfigMap you created earlier.
 
-## Set up CCS/R [ec_setup_ccsr]
+### Configure external access to the transport interface of your ECK cluster
+
+:::{include} _snippets/eck_expose_transport.md
+:::
+
+::::::
+:::::::
+
+## Connect to the remote cluster [ec_connect_to_the_remote_cluster_4]
+
+:::{include} _snippets/eck_rcs_connect_intro.md
+:::
+
+### Using {{kib}} [ec_using_kibana_4]
 
-Now that trust has been established, you can set up CCS/R from the ECK cluster to the ECH cluster or from the ECH cluster to the ECK cluster.
+:::{include} _snippets/rcs-kibana-api-snippet-self.md
+:::
 
-### ECK Cluster to {{ech}} cluster [ec_eck_cluster_to_elasticsearch_service_cluster]
+### Using the {{es}} API [ec_using_the_elasticsearch_api_4]
 
-Configure the ECH deployment as a remote on your ECK cluster following [](ec-remote-cluster-self-managed.md#ec_connect_to_the_remote_cluster_4) steps.
+:::{include} _snippets/rcs-elasticsearch-api-snippet-self.md
+:::
 
-### {{ech}} cluster to ECK Cluster [ec_elasticsearch_service_cluster_to_eck_cluster]
+## Configure roles and users [ec_configure_roles_and_users_4]
 
-Follow the steps outlined in the [ECK documentation](/deploy-manage/remote-clusters/eck-remote-clusters.md#k8s_configure_the_remote_cluster_connection_through_the_elasticsearch_rest_api) to expose the transport layer of your ECK cluster, and configure the ECK cluster as a remote of your ECH deployment.
+:::{include} _snippets/configure-roles-and-users.md
+:::
diff --git a/deploy-manage/remote-clusters/ece-enable-ccs-for-eck.md b/deploy-manage/remote-clusters/ece-enable-ccs-for-eck.md
