From 9f183f2588d53bb37bb81e8b2034fd274affe493 Mon Sep 17 00:00:00 2001
From: Liam Thompson <leemthompo@gmail.com>
Date: Wed, 7 Aug 2024 17:57:07 +0200
Subject: [PATCH] [DOCS] Document CCS enrich with api-key based auth

---
 .../esql/esql-across-clusters.asciidoc        | 51 ++++++++++++++++---
 1 file changed, 45 insertions(+), 6 deletions(-)

diff --git a/docs/reference/esql/esql-across-clusters.asciidoc b/docs/reference/esql/esql-across-clusters.asciidoc
index 8bc1e2a83fc19..122d8c96c18a7 100644
--- a/docs/reference/esql/esql-across-clusters.asciidoc
+++ b/docs/reference/esql/esql-across-clusters.asciidoc
@@ -54,11 +54,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.
@@ -114,6 +109,49 @@ 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.
 
+[discrete]
+[[esql-ccs-security-model-api-key-enrich]]
+====== Enrich with API key authentication
+
+The ability to enrich across clusters with the API key based security model was introduced in version *8.15.0*.
+
+The following example API call creates a role that can query remote `.enrich` indices using {esql}. 
+The `monitor_enrich` privilege enables the user to perform read-only operations for managing and executing enrich policies on the remote cluster, when using the API key based security model.
+
+[source,console]
+----
+POST /_security/role/remote1
+{
+  "cluster": ["cross_cluster_search"], <1> 
+  "indices": [
+    { 
+      "names" : [""],
+      "privileges": ["read"]
+    }
+  ], 
+  "remote_indices": [
+    {
+      "names": [ "logs-*" ],
+      "privileges": [ "read","read_cross_cluster" ],
+      "clusters" : ["my_remote_cluster"]
+    }
+  ],
+   "remote_cluster": [ <2>
+        {
+            "privileges": [
+                "monitor_enrich"
+            ],
+            "clusters": [
+                "my_remote_cluster"
+            ]
+        }
+    ]
+} 
+----
+
+<1> Like the first example, the `cross_cluster_search` cluster privilege is required for the _local_ cluster.
+<2> This is 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*.
+
 [discrete]
 [[ccq-remote-cluster-setup]]
 ==== Remote cluster setup
@@ -176,7 +214,8 @@ clusters is critical for ES|QL to produce a consistent query result.
 
 [NOTE]
 ====
-Enrich across clusters is *not supported* in this version when using {esql} with the <<remote-clusters-api-key, *API key based security model*>>.
+There are specific requirements to enable enrich across clusters with the API key based security model.
+Refer to <<esql-ccs-security-model-api-key-enrich,Enrich with API key authentication>> for more information.
 ====
 
 In the following example, the enrich with `hosts` policy can be executed on