Skip to content

Commit 1704af5

Browse files
eedugonshainaraskas
authored and
naemono
committed
Remote clusters: Snippets and improvements for ECE and ECH use cases (elastic#3365)
Converting part of the content to snippets and improving the Kibana UI instructions (they were outdated). Relates to elastic#3093 --------- Co-authored-by: shainaraskas <[email protected]>
1 parent a88f394 commit 1704af5

10 files changed

+148
-540
lines changed

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

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ This snippet is in use in the following locations:
55
-->
66
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:
77

8+
* `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**.
89
* `mode`: `proxy`
910
* `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.
1011

@@ -16,17 +17,17 @@ To configure a self-managed cluster as a remote cluster, use the [cluster update
1617

1718
* `server_name`: Specify a value if the certificate presented by the remote cluster is signed for a different name than the proxy_address.
1819

19-
This is an example of the API call to `_cluster/settings`:
20+
This is an example of the API call to add or update a remote cluster:
2021

2122
```json
2223
PUT /_cluster/settings
2324
{
2425
"persistent": {
2526
"cluster": {
2627
"remote": {
27-
"alias-for-my-remote-cluster": {
28+
"alias-for-my-remote-cluster": { // Align the alias with the remote cluster name used when adding the API key.
2829
"mode":"proxy",
29-
"proxy_address": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9300",
30+
"proxy_address": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400",
3031
"server_name": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io"
3132
}
3233
}
@@ -35,8 +36,4 @@ PUT /_cluster/settings
3536
}
3637
```
3738

38-
::::{note}
39-
When using API key authentication, the cluster alias must match the one you configured when adding the API key in the Cloud UI.
40-
::::
41-
42-
For a full list of available client connection settings in proxy mode, refer to [remote cluster settings reference](elasticsearch://reference/elasticsearch/configuration-reference/remote-clusters.md#remote-cluster-proxy-settings).
39+
For a full list of available client connection settings in proxy mode, refer to the [remote cluster settings reference](elasticsearch://reference/elasticsearch/configuration-reference/remote-clusters.md#remote-cluster-proxy-settings).

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

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
<!--
2+
This snippet is in use in the following locations:
3+
- ec-remote-cluster-same-ess.md
4+
- ec-remote-cluster-other-ess.md
5+
- ec-remote-cluster-ece.md
6+
- ece-remote-cluster-same-ece.md
7+
- ece-remote-cluster-other-ece.md
8+
- ece-remote-cluster-ess.md
9+
10+
It requires remote_type substitution to be defined
11+
-->
12+
To configure a deployment 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:
13+
14+
* `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**.
15+
* `mode`: `proxy`
16+
* `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.
17+
18+
Using the API, this value can be obtained from the {{es}} resource info, concatenating the field `metadata.endpoint` and port `9400` using a semicolon.
19+
20+
::::{note}
21+
If you’re using API keys as security model, change the port to `9443`.
22+
::::
23+
24+
* `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.
25+
26+
Using the API, this can be obtained from the {{es}} resource info field `metadata.endpoint`.
27+
28+
This example shows the API call to add or update a remote cluster. The alias `alias-for-my-remote-cluster` must match the remote cluster name used when adding the API key to the deployment:
29+
30+
```json
31+
PUT /_cluster/settings
32+
{
33+
"persistent": {
34+
"cluster": {
35+
"remote": {
36+
"alias-for-my-remote-cluster": { // Remote cluster alias
37+
"mode":"proxy",
38+
"proxy_address": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400",
39+
"server_name": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io"
40+
}
41+
}
42+
}
43+
}
44+
}
45+
```
46+
47+
For a full list of available client connection settings in proxy mode, refer to the [remote cluster settings reference](elasticsearch://reference/elasticsearch/configuration-reference/remote-clusters.md#remote-cluster-proxy-settings).

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<!--
2+
This snippet is in use in the following locations:
3+
- ec-remote-cluster-same-ess.md
4+
- ec-remote-cluster-other-ess.md
5+
- ec-remote-cluster-ece.md
6+
- ece-remote-cluster-same-ece.md
7+
- ece-remote-cluster-other-ece.md
8+
- ece-remote-cluster-ess.md
9+
10+
It requires remote_type substitution to be defined
11+
-->
12+
1. Go to the **Remote Clusters** management page in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md).
13+
2. Select **Add a remote cluster**.
14+
2. In **Select connection type**, choose the authentication mechanism you prepared earlier (**API keys** or **Certificates**), and then click **Next**.
15+
3. In **Add connection information**, fill in the following fields:
16+
17+
* **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.
18+
19+
When using API key authentication, this alias must match the **Remote cluster name** you configured when adding the API key in the Cloud UI.
20+
21+
* **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.
22+
23+
::::{note}
24+
If you’re using API keys as security model, change the port to `9443`.
25+
::::
26+
27+
* **Configure advanced options** (optional): Expand this section if you need to customize additional settings.
28+
* **TLS server name**: Specify a value if the certificate presented by the remote cluster is signed for a different name than the remote address.
29+
30+
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.
31+
32+
* **Socket connections**: Define the number of connections to open with the remote cluster.
33+
34+
For a full list of available client connection settings, refer to the [remote cluster settings reference](elasticsearch://reference/elasticsearch/configuration-reference/remote-clusters.md#remote-cluster-proxy-settings).
35+
36+
4. Click **Next**.
37+
5. In **Confirm setup**, click **Add remote cluster** (you have already established trust in a previous step).

‎deploy-manage/remote-clusters/ec-remote-cluster-ece.md‎

Lines changed: 8 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ applies_to:
88
ece: ga
99
products:
1010
- id: cloud-hosted
11+
sub:
12+
remote_type: Elastic Cloud Enterprise deployment
1113
---
1214

1315
# Connect {{ech}} deployments to an {{ece}} environment [ec-remote-cluster-ece]
@@ -201,114 +203,17 @@ On the local cluster, add the remote cluster using {{kib}} or the {{es}} API.
201203

202204
### Using {{kib}} [ec_using_kibana_3]
203205

204-
1. Go to the **Remote Clusters** management page in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md).
205-
2. Select **Add a remote cluster**.
206-
2. Enable **Manually enter proxy address and server name**.
207-
3. Fill in the following fields:
208-
209-
* **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.
210-
211-
When using API key authentication, this alias must match the **Remote cluster name** you configured when adding the API key in the Cloud UI.
212-
* **Proxy address**: This value can be found on the **Security** page of the {{ece}} deployment you want to use as a remote.<br>
213-
214-
::::{tip}
215-
If you’re using API keys as security model, change the port into `9443`.
216-
::::
217-
218-
* **Server name**: This value can be found on the **Security** page of the {{ece}} deployment you want to use as a remote.
219-
220-
:::{image} /deploy-manage/images/cloud-enterprise-ce-copy-remote-cluster-parameters.png
221-
:alt: Remote Cluster Parameters in Deployment
222-
:screenshot:
223-
:::
224-
225-
::::{note}
226-
If you’re having issues establishing the connection and the remote cluster is part of an {{ece}} environment with a private certificate, make sure that the proxy address and server name match with the the certificate information. For more information, refer to [Administering endpoints in {{ece}}](/deploy-manage/deploy/cloud-enterprise/change-endpoint-urls.md).
227-
::::
228-
229-
4. Click **Next**.
230-
5. Click **Add remote cluster** (you have already established trust in a previous step).
231-
232-
233-
### Using the {{es}} API [ec_using_the_elasticsearch_api_3]
234-
235-
To configure a deployment 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:
236-
237-
* `mode`: `proxy`
238-
* `proxy_address`: This value can be found on the **Security** page of the {{ech}} deployment you want to use as a remote. Also, using the API, this value can be obtained from the {{es}} resource info, concatenating the field `metadata.endpoint` and port `9400` using a semicolon.
239-
240-
::::{tip}
241-
If you’re using API keys as security model, change the port into `9443`.
242-
::::
243-
244-
245-
* `server_name`: This value can be found on the **Security** page of the {{ech}} deployment you want to use as a remote. Also, using the API, this can be obtained from the {{es}} resource info field `metadata.endpoint`.
246-
247-
This is an example of the API call to `_cluster/settings`:
248-
249-
```json
250-
PUT /_cluster/settings
251-
{
252-
"persistent": {
253-
"cluster": {
254-
"remote": {
255-
"alias-for-my-remote-cluster": {
256-
"mode":"proxy",
257-
"proxy_address": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400",
258-
"server_name": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io"
259-
}
260-
}
261-
}
262-
}
263-
}
264-
```
265-
266-
::::{note}
267-
When using API key authentication, the cluster alias must match the one you configured when adding the API key in the Cloud UI.
268-
::::
269-
270-
### Using the {{ecloud}} RESTful API [ec_using_the_elasticsearch_service_restful_api_3]
206+
:::{include} _snippets/rcs-kibana-api-snippet.md
207+
:::
271208

272209
::::{note}
273-
This section only applies if you’re using TLS certificates as cross-cluster security model and when both clusters belong to the same organization. For other scenarios, the [{{es}} API](#ec_using_the_elasticsearch_api_3) should be used instead.
210+
If you’re having issues establishing the connection and the remote cluster is part of an {{ece}} environment with a private certificate, make sure that the proxy address and server name match with the the certificate information. For more information, refer to [Administering endpoints in {{ece}}](/deploy-manage/deploy/cloud-enterprise/change-endpoint-urls.md).
274211
::::
275212

213+
### Using the {{es}} API [ec_using_the_elasticsearch_api_3]
276214

277-
```sh
278-
curl -H 'Content-Type: application/json' -X PUT -H "Authorization: ApiKey $EC_API_KEY" https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters -d '
279-
{
280-
"resources" : [
281-
{
282-
"deployment_id": "$DEPLOYMENT_ID_REMOTE",
283-
"elasticsearch_ref_id": "$REF_ID_REMOTE",
284-
"alias": "alias-your-remote",
285-
"skip_unavailable" : true
286-
}
287-
]
288-
}'
289-
```
290-
291-
`DEPLOYMENT_ID_REMOTE`
292-
: The ID of your remote deployment, as shown in the Cloud UI or obtained through the API.
293-
294-
`REF_ID_REMOTE`
295-
: The unique ID of the {{es}} resources inside your remote deployment (you can obtain these values through the API).
296-
297-
Note the following when using the {{ecloud}} RESTful API:
298-
299-
1. A cluster alias must contain only letters, numbers, dashes (-), or underscores (_).
300-
2. To learn about skipping disconnected clusters, refer to the [{{es}} documentation](/solutions/search/cross-cluster-search.md#skip-unavailable-clusters).
301-
3. When remote clusters are already configured for a deployment, the `PUT` request replaces the existing configuration with the new configuration passed. Passing an empty array of resources will remove all remote clusters.
302-
303-
The following API request retrieves the remote clusters configuration:
304-
305-
```sh
306-
curl -X GET -H "Authorization: ApiKey $EC_API_KEY" https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters
307-
```
308-
309-
::::{note}
310-
The response will include just the remote clusters from the same {{ecloud}} organization. In order to obtain the whole list of remote clusters, use {{kib}} or the [{{es}} API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-remote-info) directly.
311-
::::
215+
:::{include} _snippets/rcs-elasticsearch-api-snippet.md
216+
:::
312217

313218
## Configure roles and users [ec_configure_roles_and_users_3]
314219

‎deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md‎

Lines changed: 6 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ applies_to:
77
ess: ga
88
products:
99
- id: cloud-hosted
10+
sub:
11+
remote_type: Elastic Cloud Hosted deployment
1012
---
1113

1214
# Connect to deployments in another {{ecloud}} organization [ec-remote-cluster-other-ess]
@@ -139,109 +141,14 @@ On the local cluster, add the remote cluster using {{kib}} or the {{es}} API.
139141

140142
### Using {{kib}} [ec_using_kibana_2]
141143

142-
1. Go to the **Remote Clusters** management page in the navigation menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md).
143-
2. Select **Add a remote cluster**.
144-
2. Enable **Manually enter proxy address and server name**.
145-
3. Fill in the following fields:
146-
147-
* **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.
148-
149-
When using API key authentication, this alias must match the **Remote cluster name** you configured when adding the API key in the Cloud UI.
150-
* **Proxy address**: This value can be found on the **Security** page of the {{ech}} deployment you want to use as a remote.<br>
151-
152-
::::{tip}
153-
If you’re using API keys as security model, change the port into `9443`.
154-
::::
155-
156-
* **Server name**: This value can be found on the **Security** page of the {{ech}} deployment you want to use as a remote.
157-
158-
::::{note}
159-
If you’re having issues establishing the connection and the remote cluster is part of an {{ece}} environment with a private certificate, make sure that the proxy address and server name match with the the certificate information. For more information, refer to [Administering endpoints in {{ece}}](/deploy-manage/deploy/cloud-enterprise/change-endpoint-urls.md).
160-
::::
161-
162-
4. Click **Next**.
163-
5. Click **Add remote cluster** (you have already established trust in a previous step).
144+
:::{include} _snippets/rcs-kibana-api-snippet.md
145+
:::
164146

165147

166148
### Using the {{es}} API [ec_using_the_elasticsearch_api_2]
167149

168-
To configure a deployment 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:
169-
170-
* `mode`: `proxy`
171-
* `proxy_address`: This value can be found on the **Security** page of the {{ech}} deployment you want to use as a remote. Also, using the API, this value can be obtained from the {{es}} resource info, concatenating the field `metadata.endpoint` and port `9400` using a semicolon.
172-
173-
::::{tip}
174-
If you’re using API keys as security model, change the port into `9443`.
175-
::::
176-
177-
178-
* `server_name`: This value can be found on the **Security** page of the {{ech}} deployment you want to use as a remote. Also, using the API, this can be obtained from the {{es}} resource info field `metadata.endpoint`.
179-
180-
This is an example of the API call to `_cluster/settings`:
181-
182-
```json
183-
PUT /_cluster/settings
184-
{
185-
"persistent": {
186-
"cluster": {
187-
"remote": {
188-
"alias-for-my-remote-cluster": {
189-
"mode":"proxy",
190-
"proxy_address": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io:9400",
191-
"server_name": "a542184a7a7d45b88b83f95392f450ab.192.168.44.10.ip.es.io"
192-
}
193-
}
194-
}
195-
}
196-
}
197-
```
198-
199-
::::{note}
200-
When using API key authentication, the cluster alias must match the one you configured when adding the API key in the Cloud UI.
201-
::::
202-
203-
### Using the {{ecloud}} RESTful API [ec_using_the_elasticsearch_service_restful_api_2]
204-
205-
::::{note}
206-
This section only applies if you’re using TLS certificates as cross-cluster security model and when both clusters belong to the same organization. For other scenarios, the [{{es}} API](#ec_using_the_elasticsearch_api_2) should be used instead.
207-
::::
208-
209-
210-
```sh
211-
curl -H 'Content-Type: application/json' -X PUT -H "Authorization: ApiKey $EC_API_KEY" https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters -d '
212-
{
213-
"resources" : [
214-
{
215-
"deployment_id": "$DEPLOYMENT_ID_REMOTE",
216-
"elasticsearch_ref_id": "$REF_ID_REMOTE",
217-
"alias": "alias-your-remote",
218-
"skip_unavailable" : true
219-
}
220-
]
221-
}'
222-
```
223-
224-
`DEPLOYMENT_ID_REMOTE`
225-
: The ID of your remote deployment, as shown in the Cloud UI or obtained through the API.
226-
227-
`REF_ID_REMOTE`
228-
: The unique ID of the {{es}} resources inside your remote deployment (you can obtain these values through the API).
229-
230-
Note the following when using the {{ecloud}} RESTful API:
231-
232-
1. A cluster alias must contain only letters, numbers, dashes (-), or underscores (_).
233-
2. To learn about skipping disconnected clusters, refer to the [{{es}} documentation](/solutions/search/cross-cluster-search.md#skip-unavailable-clusters).
234-
3. When remote clusters are already configured for a deployment, the `PUT` request replaces the existing configuration with the new configuration passed. Passing an empty array of resources will remove all remote clusters.
235-
236-
The following API request retrieves the remote clusters configuration:
237-
238-
```sh
239-
curl -X GET -H "Authorization: ApiKey $EC_API_KEY" https://api.elastic-cloud.com/api/v1/deployments/$DEPLOYMENT_ID/elasticsearch/$REF_ID/remote-clusters
240-
```
241-
242-
::::{note}
243-
The response will include just the remote clusters from the same {{ecloud}} organization. In order to obtain the whole list of remote clusters, use {{kib}} or the [{{es}} API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-remote-info) directly.
244-
::::
150+
:::{include} _snippets/rcs-elasticsearch-api-snippet.md
151+
:::
245152

246153
## Configure roles and users [ec_configure_roles_and_users_2]
247154

0 commit comments

Comments
 (0)