Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[8.15] [DOCS] Document CCS enrich with api-key based auth (#111682) #111685

Merged
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 22 additions & 8 deletions docs/reference/esql/esql-across-clusters.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -49,11 +49,6 @@ Refer to <<remote-clusters-cert, TLS certificate authentication>> for prerequisi
[[esql-ccs-security-model-api-key]]
===== API key authentication

[NOTE]
====
`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 <<remote-clusters-api-key, *API key based security model*>>. 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.
Expand All @@ -66,6 +61,7 @@ You will need to:

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.
The final privilege, `remote_cluster`, is required to allow remote enrich operations.

[source,console]
----
Expand All @@ -84,7 +80,17 @@ POST /_security/role/remote1
"privileges": [ "read","read_cross_cluster" ], <4>
"clusters" : ["my_remote_cluster"] <5>
}
]
],
"remote_cluster": [ <6>
{
"privileges": [
"monitor_enrich"
],
"clusters": [
"my_remote_cluster"
]
}
]
}
----

Expand All @@ -95,6 +101,7 @@ POST /_security/role/remote1
<5> The remote clusters to which these privileges apply.
This remote cluster must be configured with a <<security-api-create-cross-cluster-api-key,cross-cluster API key>> and connected to the remote cluster before the remote index can be queried.
Verify connection using the <<cluster-remote-info, Remote cluster info>> API.
<6> Required to allow remote enrichment. Without this, the user cannot read from the `.enrich` indices on the remote cluster. The `remote_cluster` security privilege was introduced in version *8.15.0*.

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.

Expand All @@ -109,6 +116,11 @@ POST /_security/user/remote_user

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.

[TIP]
====
Cross cluster API keys created in versions prior to 8.15.0 will need to replaced or updated to add the new permissions required for {esql} with ENRICH.
====

[discrete]
[[ccq-remote-cluster-setup]]
==== Remote cluster setup
Expand Down Expand Up @@ -169,9 +181,11 @@ clusters, aiming to minimize computation or inter-cluster data transfer. Ensurin
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]
[TIP]
====
Enrich across clusters is *not supported* in this version when using {esql} with the <<remote-clusters-api-key, *API key based security model*>>.
Enrich in {esql} across clusters using the API key based security model was introduced in version *8.15.0*.
Cross cluster API keys created in versions prior to 8.15.0 will need to replaced or updated to use the new required permissions.
Refer to the example in the <<esql-ccs-security-model-api-key,API key authentication>> section.
====

In the following example, the enrich with `hosts` policy can be executed on
Expand Down
Loading