From be28bc4517e9b4b28002cb0163e2feda5bcbfb71 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 29 May 2024 12:22:41 +0200 Subject: [PATCH 1/9] [DOCS][ESQL][8.14] Add API key based security model info for ESQL CCS --- .../esql/esql-across-clusters.asciidoc | 77 +++++++++++++++---- 1 file changed, 63 insertions(+), 14 deletions(-) diff --git a/docs/reference/esql/esql-across-clusters.asciidoc b/docs/reference/esql/esql-across-clusters.asciidoc index 95278314b0253..c94aaaee0a1be 100644 --- a/docs/reference/esql/esql-across-clusters.asciidoc +++ b/docs/reference/esql/esql-across-clusters.asciidoc @@ -1,6 +1,5 @@ [[esql-cross-clusters]] === Using {esql} across clusters - ++++ Using {esql} across clusters ++++ @@ -11,6 +10,8 @@ preview::["{ccs-cap} for {esql} is in technical preview and may be changed or re With {esql}, you can execute a single query across multiple clusters. +[discrete] +[[esql-ccs-prerequisites]] ==== Prerequisites include::{es-ref-dir}/search/search-your-data/search-across-clusters.asciidoc[tag=ccs-prereqs] @@ -19,6 +20,49 @@ include::{es-ref-dir}/search/search-your-data/search-across-clusters.asciidoc[ta include::{es-ref-dir}/search/search-your-data/search-across-clusters.asciidoc[tag=ccs-proxy-mode] +[discrete] +[[esql-ccs-security-model]] +==== Security model + +[discrete] +[[esql-ccs-security-model-api-key]] +===== API key authentication + +[NOTE] +==== +The `ENRICH` keyword is *not supported* until 8.15 when using {esql} with the API key based security model. +==== + +The following information pertains to using {esql} across clusters with the <>. +API key based cross-cluster search (CCS) enables more granular control over allowed actions between clusters. + +You will need to create an API key using the <> API or using the {kibana-ref}/api-keys.html[Kibana API keys UI]. + +The following example API call creates a role that can query remote indices using {esql} with the API key based security model. + +[source,console] +---- +POST /_security/role/remote1 +{ + "indices": [ + { + "names" : [""], <2> + "privileges": ["read"] + } + ], + "remote_indices": [ + { + "names": [ "logs-*" ], + "privileges": [ "read","read_cross_cluster" ], <1> + "clusters" : ["my_remote_cluster"] + } + ] +} +---- + +<1> The `read_cross_cluster` privilege is always required when using {esql} across clusters with the API key based security model. +<2> The `names` field must be an empty string when using the `remote_indices` field. This is only needed for roles that can ONLY search the remote cluster. Typically, users will have both local permission and remote permissions. + [discrete] [[ccq-remote-cluster-setup]] ==== Remote cluster setup @@ -71,13 +115,18 @@ FROM *:my-index-000001 Enrich in {esql} across clusters operates similarly to <>. If the enrich policy and its enrich indices are consistent across all clusters, simply write the enrich command as you would without remote clusters. In this default mode, -{esql} can execute the enrich command on either the querying cluster or the fulfilling +{esql} can execute the enrich command on either the local cluster or the remote clusters, aiming to minimize computation or inter-cluster data transfer. Ensuring that -the policy exists with consistent data on both the querying cluster and the fulfilling +the policy exists with consistent data on both the local cluster and the remote clusters is critical for ES|QL to produce a consistent query result. +[NOTE] +==== +Enrich across clusters is *not supported* until 8.15 when using {esql} with the <>. +==== + In the following example, the enrich with `hosts` policy can be executed on -either the querying cluster or the remote cluster `cluster_one`. +either the local cluster or the remote cluster `cluster_one`. [source,esql] ---- @@ -87,8 +136,8 @@ FROM my-index-000001,cluster_one:my-index-000001 ---- Enrich with an {esql} query against remote clusters only can also happen on -the querying cluster. This means the below query requires the `hosts` enrich -policy to exist on the querying cluster as well. +the local cluster. This means the below query requires the `hosts` enrich +policy to exist on the local cluster as well. [source,esql] ---- @@ -99,10 +148,10 @@ FROM cluster_one:my-index-000001,cluster_two:my-index-000001 [discrete] [[esql-enrich-coordinator]] -==== Enrich with coordinator mode +===== Enrich with coordinator mode {esql} provides the enrich `_coordinator` mode to force {esql} to execute the enrich -command on the querying cluster. This mode should be used when the enrich policy is +command on the local cluster. This mode should be used when the enrich policy is not available on the remote clusters or maintaining consistency of enrich indices across clusters is challenging. @@ -118,21 +167,21 @@ FROM my-index-000001,cluster_one:my-index-000001 [IMPORTANT] ==== Enrich with the `_coordinator` mode usually increases inter-cluster data transfer and -workload on the querying cluster. +workload on the local cluster. ==== [discrete] [[esql-enrich-remote]] -==== Enrich with remote mode +===== Enrich with remote mode {esql} also provides the enrich `_remote` mode to force {esql} to execute the enrich -command independently on each fulfilling cluster where the target indices reside. +command independently on each remote cluster where the target indices reside. This mode is useful for managing different enrich data on each cluster, such as detailed information of hosts for each region where the target (main) indices contain log events from these hosts. In the below example, the `hosts` enrich policy is required to exist on all -fulfilling clusters: the `querying` cluster (as local indices are included), +remote clusters: the `querying` cluster (as local indices are included), the remote cluster `cluster_one`, and `cluster_two`. [source,esql] @@ -157,12 +206,12 @@ FROM my-index-000001,cluster_one:my-index-000001,cluster_two:my-index-000001 [discrete] [[esql-multi-enrich]] -==== Multiple enrich commands +===== Multiple enrich commands You can include multiple enrich commands in the same query with different modes. {esql} will attempt to execute them accordingly. For example, this query performs two enriches, first with the `hosts` policy on any cluster -and then with the `vendors` policy on the querying cluster. +and then with the `vendors` policy on the local cluster. [source,esql] ---- From f5655633c31ee18d5fb83923136ec64d8def9834 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 30 May 2024 11:19:35 +0200 Subject: [PATCH 2/9] Add overview of both security models, tweak per review --- .../esql/esql-across-clusters.asciidoc | 26 +++++++++++++++---- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/docs/reference/esql/esql-across-clusters.asciidoc b/docs/reference/esql/esql-across-clusters.asciidoc index c94aaaee0a1be..4758c5af2998a 100644 --- a/docs/reference/esql/esql-across-clusters.asciidoc +++ b/docs/reference/esql/esql-across-clusters.asciidoc @@ -24,13 +24,26 @@ include::{es-ref-dir}/search/search-your-data/search-across-clusters.asciidoc[ta [[esql-ccs-security-model]] ==== Security model +{es} supports two security models for cross-cluster search (CCS): + +* <> +* <> + +[discrete] +[[esql-ccs-security-model-certificate]] +===== TLS certificate authentication + +Refer to <> for prerequisites and detailed setup instructions. + +Importantly, you must ensure that the same named roles and privileges are identical in both clusters. + [discrete] [[esql-ccs-security-model-api-key]] ===== API key authentication [NOTE] ==== -The `ENRICH` keyword is *not supported* until 8.15 when using {esql} with the API key based security model. +`ENRICH` is *not supported* in this version when using {esql} with the API key based security model. ==== The following information pertains to using {esql} across clusters with the <>. @@ -50,18 +63,21 @@ POST /_security/role/remote1 "privileges": ["read"] } ], - "remote_indices": [ + "remote_indices": [ <3> { "names": [ "logs-*" ], "privileges": [ "read","read_cross_cluster" ], <1> - "clusters" : ["my_remote_cluster"] + "clusters" : ["my_remote_cluster"] <4> } ] } ---- <1> The `read_cross_cluster` privilege is always required when using {esql} across clusters with the API key based security model. -<2> The `names` field must be an empty string when using the `remote_indices` field. This is only needed for roles that can ONLY search the remote cluster. Typically, users will have both local permission and remote permissions. +<2> Typically, users will have permissions to read both local and remote indices. However, for cases where the role is intended to ONLY search the remote cluster, the `read` permission is still required for the local cluster. To provide read access to the local cluster, but disallow reading any indices in the local cluster, the `names` field may be an empty string. +<3> The indices allowed read access to the remote cluster. The configured <> must also allow this index to be read. +<4> The remote clusters to which these privileges apply. This remote cluster must be configured with a <> and connected to the remote cluster before the remote index can be queried. +Verify connection using the <> API. [discrete] [[ccq-remote-cluster-setup]] @@ -122,7 +138,7 @@ clusters is critical for ES|QL to produce a consistent query result. [NOTE] ==== -Enrich across clusters is *not supported* until 8.15 when using {esql} with the <>. +Enrich across clusters is *not supported* in this version when using {esql} with the <>. ==== In the following example, the enrich with `hosts` policy can be executed on From 9e6100148f2f8690e7415e313bc0404e8a9bc4ed Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 30 May 2024 11:54:59 +0200 Subject: [PATCH 3/9] Add practical info about differences when choosing security model --- docs/reference/esql/esql-across-clusters.asciidoc | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/reference/esql/esql-across-clusters.asciidoc b/docs/reference/esql/esql-across-clusters.asciidoc index 4758c5af2998a..aad3d7cd5342f 100644 --- a/docs/reference/esql/esql-across-clusters.asciidoc +++ b/docs/reference/esql/esql-across-clusters.asciidoc @@ -29,14 +29,15 @@ include::{es-ref-dir}/search/search-your-data/search-across-clusters.asciidoc[ta * <> * <> + [discrete] [[esql-ccs-security-model-certificate]] ===== TLS certificate authentication +TLS certificate authentication makes sense in single administrator scenarios where you have full control over both clusters. +Importantly, you must ensure that named roles and their privileges are identical in both clusters. Refer to <> for prerequisites and detailed setup instructions. -Importantly, you must ensure that the same named roles and privileges are identical in both clusters. - [discrete] [[esql-ccs-security-model-api-key]] ===== API key authentication @@ -47,7 +48,9 @@ Importantly, you must ensure that the same named roles and privileges are identi ==== The following information pertains to using {esql} across clusters with the <>. -API key based cross-cluster search (CCS) enables more granular control over allowed actions between clusters. +API key based cross-cluster search (CCS) enables more granular control over allowed actions between clusters. +As a result defining roles and privileges is more complex than with the certificate based security model. +It makes sense when you have different administrators for different clusters. You will need to create an API key using the <> API or using the {kibana-ref}/api-keys.html[Kibana API keys UI]. From e6aef46d8675388a98df279e60396384ec87dda7 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 30 May 2024 11:56:39 +0200 Subject: [PATCH 4/9] Copyedit, formatting --- docs/reference/esql/esql-across-clusters.asciidoc | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/reference/esql/esql-across-clusters.asciidoc b/docs/reference/esql/esql-across-clusters.asciidoc index aad3d7cd5342f..d5cf192b7b272 100644 --- a/docs/reference/esql/esql-across-clusters.asciidoc +++ b/docs/reference/esql/esql-across-clusters.asciidoc @@ -29,7 +29,6 @@ include::{es-ref-dir}/search/search-your-data/search-across-clusters.asciidoc[ta * <> * <> - [discrete] [[esql-ccs-security-model-certificate]] ===== TLS certificate authentication @@ -49,8 +48,8 @@ Refer to <> for prerequisi The following information pertains to using {esql} across clusters with the <>. API key based cross-cluster search (CCS) enables more granular control over allowed actions between clusters. -As a result defining roles and privileges is more complex than with the certificate based security model. -It makes sense when you have different administrators for different clusters. +As a result, defining roles and privileges is more complex than with the certificate based security model. +For example, it makes sense in scenarios when you have different administrators for different clusters. You will need to create an API key using the <> API or using the {kibana-ref}/api-keys.html[Kibana API keys UI]. From c429b950288fe710d82b6020427dc96b41647478 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 30 May 2024 12:44:07 +0200 Subject: [PATCH 5/9] Add cluster privilege --- docs/reference/esql/esql-across-clusters.asciidoc | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/reference/esql/esql-across-clusters.asciidoc b/docs/reference/esql/esql-across-clusters.asciidoc index d5cf192b7b272..240acb08f011b 100644 --- a/docs/reference/esql/esql-across-clusters.asciidoc +++ b/docs/reference/esql/esql-across-clusters.asciidoc @@ -59,28 +59,31 @@ The following example API call creates a role that can query remote indices usin ---- POST /_security/role/remote1 { + "cluster": ["cross_cluster_search"], <2> "indices": [ { - "names" : [""], <2> + "names" : [""], <3> "privileges": ["read"] } ], - "remote_indices": [ <3> + "remote_indices": [ <4> { "names": [ "logs-*" ], "privileges": [ "read","read_cross_cluster" ], <1> - "clusters" : ["my_remote_cluster"] <4> + "clusters" : ["my_remote_cluster"] <5> } ] } ---- <1> The `read_cross_cluster` privilege is always required when using {esql} across clusters with the API key based security model. -<2> Typically, users will have permissions to read both local and remote indices. However, for cases where the role is intended to ONLY search the remote cluster, the `read` permission is still required for the local cluster. To provide read access to the local cluster, but disallow reading any indices in the local cluster, the `names` field may be an empty string. -<3> The indices allowed read access to the remote cluster. The configured <> must also allow this index to be read. -<4> The remote clusters to which these privileges apply. This remote cluster must be configured with a <> and connected to the remote cluster before the remote index can be queried. +<2> The `cross_cluster_search` cluster privilege is also required. +<3> Typically, users will have permissions to read both local and remote indices. However, for cases where the role is intended to ONLY search the remote cluster, the `read` permission is still required for the local cluster. To provide read access to the local cluster, but disallow reading any indices in the local cluster, the `names` field may be an empty string. +<4> The indices allowed read access to the remote cluster. The configured <> must also allow this index to be read. +<5> The remote clusters to which these privileges apply. This remote cluster must be configured with a <> and connected to the remote cluster before the remote index can be queried. Verify connection using the <> API. + [discrete] [[ccq-remote-cluster-setup]] ==== Remote cluster setup From 03d40b9a37397988da30c352e6bbb00162a5a028 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Thu, 30 May 2024 15:08:47 +0200 Subject: [PATCH 6/9] Clarify --- docs/reference/esql/esql-across-clusters.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/esql/esql-across-clusters.asciidoc b/docs/reference/esql/esql-across-clusters.asciidoc index 240acb08f011b..119ce60981f0a 100644 --- a/docs/reference/esql/esql-across-clusters.asciidoc +++ b/docs/reference/esql/esql-across-clusters.asciidoc @@ -77,7 +77,7 @@ POST /_security/role/remote1 ---- <1> The `read_cross_cluster` privilege is always required when using {esql} across clusters with the API key based security model. -<2> The `cross_cluster_search` cluster privilege is also required. +<2> The `cross_cluster_search` cluster privilege is also required for the _local_ cluster. <3> Typically, users will have permissions to read both local and remote indices. However, for cases where the role is intended to ONLY search the remote cluster, the `read` permission is still required for the local cluster. To provide read access to the local cluster, but disallow reading any indices in the local cluster, the `names` field may be an empty string. <4> The indices allowed read access to the remote cluster. The configured <> must also allow this index to be read. <5> The remote clusters to which these privileges apply. This remote cluster must be configured with a <> and connected to the remote cluster before the remote index can be queried. From 6c3e2a5c40fe742d1e271e2d8f066e9f078c59c1 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Fri, 31 May 2024 14:33:17 +0200 Subject: [PATCH 7/9] Updates per review --- .../esql/esql-across-clusters.asciidoc | 60 ++++++++++++++----- .../cluster/remote-clusters-api-key.asciidoc | 2 + 2 files changed, 46 insertions(+), 16 deletions(-) diff --git a/docs/reference/esql/esql-across-clusters.asciidoc b/docs/reference/esql/esql-across-clusters.asciidoc index 119ce60981f0a..41a601822c05d 100644 --- a/docs/reference/esql/esql-across-clusters.asciidoc +++ b/docs/reference/esql/esql-across-clusters.asciidoc @@ -29,12 +29,20 @@ include::{es-ref-dir}/search/search-your-data/search-across-clusters.asciidoc[ta * <> * <> +[TIP] +==== +To check which security model is being used to connect your clusters, run `GET _remote/info`. +If you're using the API key authentication method, you'll see the `"cluster_credentials"` key in the response. +==== + [discrete] [[esql-ccs-security-model-certificate]] ===== TLS certificate authentication -TLS certificate authentication makes sense in single administrator scenarios where you have full control over both clusters. -Importantly, you must ensure that named roles and their privileges are identical in both clusters. +TLS certificate authentication secures remote clusters with mutual TLS. +This could be the preferred model when a single administrator has full control over both clusters. +We generally recommend that roles and their privileges be identical in both clusters. + Refer to <> for prerequisites and detailed setup instructions. [discrete] @@ -46,47 +54,67 @@ Refer to <> for prerequisi `ENRICH` is *not supported* in this version when using {esql} with the API key based security model. ==== -The following information pertains to using {esql} across clusters with the <>. +The following information pertains to using {esql} across clusters with the <>. You'll need to follow the steps on that page for the *full setup instructions*. This page only contains additional information specific to {esql}. + API key based cross-cluster search (CCS) enables more granular control over allowed actions between clusters. -As a result, defining roles and privileges is more complex than with the certificate based security model. -For example, it makes sense in scenarios when you have different administrators for different clusters. +This may be the preferred model when you have different administrators for different clusters and want more control over who can access what data. + +You will need to: -You will need to create an API key using the <> API or using the {kibana-ref}/api-keys.html[Kibana API keys UI]. +* Create an API key on the *remote cluster* using the <> API or using the {kibana-ref}/api-keys.html[Kibana API keys UI]. +* Add the API key to the `elasticsearch.yml` file on the *local cluster*, as part of the steps in <>. All cross-cluster requests from the local cluster are bound by the API key’s privileges. -The following example API call creates a role that can query remote indices using {esql} with the API key based security model. +Using {esql} with the API key based security model requires some additional permissions that may not be needed when using the traditional query DSL based search. +The following example API call creates a role that can query remote indices using {esql} when using the API key based security model. [source,console] ---- POST /_security/role/remote1 { - "cluster": ["cross_cluster_search"], <2> + "cluster": ["cross_cluster_search"], <1> "indices": [ { - "names" : [""], <3> + "names" : [""], <2> "privileges": ["read"] } ], - "remote_indices": [ <4> + "remote_indices": [ <3> { "names": [ "logs-*" ], - "privileges": [ "read","read_cross_cluster" ], <1> + "privileges": [ "read","read_cross_cluster" ], <4> "clusters" : ["my_remote_cluster"] <5> } ] } ---- -<1> The `read_cross_cluster` privilege is always required when using {esql} across clusters with the API key based security model. -<2> The `cross_cluster_search` cluster privilege is also required for the _local_ cluster. -<3> Typically, users will have permissions to read both local and remote indices. However, for cases where the role is intended to ONLY search the remote cluster, the `read` permission is still required for the local cluster. To provide read access to the local cluster, but disallow reading any indices in the local cluster, the `names` field may be an empty string. -<4> The indices allowed read access to the remote cluster. The configured <> must also allow this index to be read. -<5> The remote clusters to which these privileges apply. This remote cluster must be configured with a <> and connected to the remote cluster before the remote index can be queried. +<1> The `cross_cluster_search` cluster privilege is required for the _local_ cluster. +<2> Typically, users will have permissions to read both local and remote indices. However, for cases where the role is intended to ONLY search the remote cluster, the `read` permission is still required for the local cluster. To provide read access to the local cluster, but disallow reading any indices in the local cluster, the `names` field may be an empty string. +<3> The indices allowed read access to the remote cluster. The configured <> must also allow this index to be read. +<4> The `read_cross_cluster` privilege is always required when using {esql} across clusters with the API key based security model. +<5> The remote clusters to which these privileges apply. +This remote cluster must be configured with a <> and connected to the remote cluster before the remote index can be queried. Verify connection using the <> API. +You will then need to create a user with the role you created above. The following example API call creates a user with the `remote1` role. + +[source,console] +---- +POST /_security/user/remote_user +{ + "password" : "", + "roles" : [ "remote1" ] +} +---- + +Remember that all cross-cluster requests from the local cluster are bound by the API key’s privileges, which are controlled by the remote cluster's administrator. [discrete] [[ccq-remote-cluster-setup]] ==== Remote cluster setup + +Once the security model is configured, you can add remote clusters. + include::{es-ref-dir}/search/search-your-data/search-across-clusters.asciidoc[tag=ccs-remote-cluster-setup] <1> Since `skip_unavailable` was not set on `cluster_three`, it uses diff --git a/docs/reference/modules/cluster/remote-clusters-api-key.asciidoc b/docs/reference/modules/cluster/remote-clusters-api-key.asciidoc index 5f462b14405ba..4aa97ce375d9f 100644 --- a/docs/reference/modules/cluster/remote-clusters-api-key.asciidoc +++ b/docs/reference/modules/cluster/remote-clusters-api-key.asciidoc @@ -63,6 +63,7 @@ information, refer to https://www.elastic.co/subscriptions. NOTE: If a remote cluster is part of an {ess} deployment, it has a valid certificate by default. You can therefore skip steps related to certificates in these instructions. +[[remote-clusters-security-api-key-remote-action]] ===== On the remote cluster // tag::remote-cluster-steps[] @@ -155,6 +156,7 @@ to the indices you want to use for {ccs} or {ccr}. You can use the need it to connect to the remote cluster later. // end::remote-cluster-steps[] +[[remote-clusters-security-api-key-local-actions]] ===== On the local cluster // tag::local-cluster-steps[] From b69c0fe55426e442edab0c1b0310429819b5359e Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Fri, 31 May 2024 14:34:55 +0200 Subject: [PATCH 8/9] Add color per review --- docs/reference/esql/esql-across-clusters.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/esql/esql-across-clusters.asciidoc b/docs/reference/esql/esql-across-clusters.asciidoc index 41a601822c05d..c06867711e7b8 100644 --- a/docs/reference/esql/esql-across-clusters.asciidoc +++ b/docs/reference/esql/esql-across-clusters.asciidoc @@ -57,7 +57,7 @@ Refer to <> for prerequisi The following information pertains to using {esql} across clusters with the <>. You'll need to follow the steps on that page for the *full setup instructions*. This page only contains additional information specific to {esql}. API key based cross-cluster search (CCS) enables more granular control over allowed actions between clusters. -This may be the preferred model when you have different administrators for different clusters and want more control over who can access what data. +This may be the preferred model when you have different administrators for different clusters and want more control over who can access what data. In this model, cluster administrators must explicitly define the access given to clusters and users. You will need to: From 62e97fc799b5116285bf2182a08a3b1c08af534a Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 3 Jun 2024 18:18:13 +0200 Subject: [PATCH 9/9] Apply Jakes's latest suggestions Co-authored-by: Jake Landis --- docs/reference/esql/esql-across-clusters.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/esql/esql-across-clusters.asciidoc b/docs/reference/esql/esql-across-clusters.asciidoc index c06867711e7b8..6231b4f4f0a69 100644 --- a/docs/reference/esql/esql-across-clusters.asciidoc +++ b/docs/reference/esql/esql-across-clusters.asciidoc @@ -62,7 +62,7 @@ This may be the preferred model when you have different administrators for diffe You will need to: * Create an API key on the *remote cluster* using the <> API or using the {kibana-ref}/api-keys.html[Kibana API keys UI]. -* Add the API key to the `elasticsearch.yml` file on the *local cluster*, as part of the steps in <>. All cross-cluster requests from the local cluster are bound by the API key’s privileges. +* Add the API key to the keystore on the *local cluster*, as part of the steps in <>. All cross-cluster requests from the local cluster are bound by the API key’s privileges. Using {esql} with the API key based security model requires some additional permissions that may not be needed when using the traditional query DSL based search. The following example API call creates a role that can query remote indices using {esql} when using the API key based security model. @@ -96,7 +96,7 @@ POST /_security/role/remote1 This remote cluster must be configured with a <> and connected to the remote cluster before the remote index can be queried. Verify connection using the <> API. -You will then need to create a user with the role you created above. The following example API call creates a user with the `remote1` role. +You will then need a user or API key with the permissions you created above. The following example API call creates a user with the `remote1` role. [source,console] ---- @@ -107,7 +107,7 @@ POST /_security/user/remote_user } ---- -Remember that all cross-cluster requests from the local cluster are bound by the API key’s privileges, which are controlled by the remote cluster's administrator. +Remember that all cross-cluster requests from the local cluster are bound by the cross cluster API key’s privileges, which are controlled by the remote cluster's administrator. [discrete] [[ccq-remote-cluster-setup]]