From c131e8c8a90c13733a7bf674eceb56b4484a1119 Mon Sep 17 00:00:00 2001
From: Jake Landis <jake.landis@elastic.co>
Date: Tue, 12 Nov 2024 09:13:37 -0600
Subject: [PATCH] Docs for monitor_stats privilege (#116533)

This commit adds docs for monitor_stats and updates an example snippet to include both remote_indices and remote_cluster.

(cherry picked from commit b7167b73e377f7d42f56646b18908eaa7069a79f)
---
 .../security/bulk-create-roles.asciidoc       |  4 +++-
 .../rest-api/security/create-roles.asciidoc   | 22 ++++++++++++++-----
 .../authorization/managing-roles.asciidoc     |  8 +++----
 .../authorization/privileges.asciidoc         |  5 +++++
 4 files changed, 27 insertions(+), 12 deletions(-)

diff --git a/docs/reference/rest-api/security/bulk-create-roles.asciidoc b/docs/reference/rest-api/security/bulk-create-roles.asciidoc
index 560e8b74cdd2c..37f49f2445770 100644
--- a/docs/reference/rest-api/security/bulk-create-roles.asciidoc
+++ b/docs/reference/rest-api/security/bulk-create-roles.asciidoc
@@ -102,7 +102,9 @@ They have no effect for remote clusters configured with the <<remote-clusters-ce
 `clusters` (required)::: (list) A list of cluster aliases to which the permissions
 in this entry apply.
 `privileges`(required)::: (list) The cluster level privileges that the owners of the role
-have in the specified clusters.
+have in the specified clusters. Note - only a subset of the cluster privileges are supported for remote clusters.
+The <<security-api-get-builtin-privileges-request, builtin privileges API>> can be used to determine
+which privileges are allowed per version.
 
 
 For more information, see <<defining-roles>>.
diff --git a/docs/reference/rest-api/security/create-roles.asciidoc b/docs/reference/rest-api/security/create-roles.asciidoc
index a1ab892330e67..d23b9f06e2d87 100644
--- a/docs/reference/rest-api/security/create-roles.asciidoc
+++ b/docs/reference/rest-api/security/create-roles.asciidoc
@@ -105,7 +105,9 @@ They have no effect for remote clusters configured with the <<remote-clusters-ce
 `clusters` (required)::: (list) A list of cluster aliases to which the permissions
 in this entry apply.
 `privileges`(required)::: (list) The cluster level privileges that the owners of the role
-have in the specified clusters.
+have in the specified clusters. Note - only a subset of the cluster privileges are supported for remote clusters.
+The <<security-api-get-builtin-privileges-request, builtin privileges API>> can be used to determine
+which privileges are allowed per version.
 
 For more information, see <<defining-roles>>.
 
@@ -176,21 +178,29 @@ POST /_security/role/cli_or_drivers_minimal
 --------------------------------------------------
 // end::sql-queries-permission[]
 
-The following example configures a role with remote indices privileges on a remote cluster:
+The following example configures a role with remote indices and remote cluster privileges for a remote cluster:
 [source,console]
 --------------------------------------------------
-POST /_security/role/role_with_remote_indices
+POST /_security/role/only_remote_access_role
 {
   "remote_indices": [
     {
-      "clusters": [ "my_remote" ], <1>
+      "clusters": ["my_remote"], <1>
       "names": ["logs*"], <2>
       "privileges": ["read", "read_cross_cluster", "view_index_metadata"] <3>
     }
+  ],
+  "remote_cluster": [
+    {
+      "clusters": ["my_remote"], <1>
+      "privileges": ["monitor_stats"]  <4>
+    }
   ]
 }
 --------------------------------------------------
 
-<1> The remote indices privileges apply to remote cluster with the alias `my_remote`.
-<2> Privileges are granted for indices matching pattern `logs*` on the remote cluster ( `my_remote`).
+<1> The remote indices and remote cluster privileges apply to remote cluster with the alias `my_remote`.
+<2> Privileges are granted for indices matching pattern `logs*` on the remote cluster (`my_remote`).
 <3> The actual <<privileges-list-indices,index privileges>> granted for `logs*` on `my_remote`.
+<4> The actual <<privileges-list-cluster,cluster privileges>> granted for `my_remote`.
+Note - only a subset of the cluster privileges are supported for remote clusters.
diff --git a/docs/reference/security/authorization/managing-roles.asciidoc b/docs/reference/security/authorization/managing-roles.asciidoc
index 535d70cbc5e9c..0c3f520605f07 100644
--- a/docs/reference/security/authorization/managing-roles.asciidoc
+++ b/docs/reference/security/authorization/managing-roles.asciidoc
@@ -249,12 +249,10 @@ The following describes the structure of a remote cluster permissions entry:
 <<api-multi-index,wildcards>> and <<regexp-syntax,regular expressions>>.
 This field is required.
 <2> The cluster level privileges for the remote cluster. The allowed values here are a subset of the
-<<privileges-list-cluster,cluster privileges>>. This field is required.
+<<privileges-list-cluster,cluster privileges>>.
+The <<security-api-get-builtin-privileges-request, builtin privileges API>> can be used to determine
+which privileges are allowed here. This field is required.
 
-The `monitor_enrich` privilege for remote clusters was introduced in version
-8.15.0. Currently, this is the only privilege available for remote clusters and
-is required to enable users to use the `ENRICH` keyword in ES|QL queries across
-clusters.
 
 ==== Example
 
diff --git a/docs/reference/security/authorization/privileges.asciidoc b/docs/reference/security/authorization/privileges.asciidoc
index 747b1eef40441..3b69e5c1ba984 100644
--- a/docs/reference/security/authorization/privileges.asciidoc
+++ b/docs/reference/security/authorization/privileges.asciidoc
@@ -250,6 +250,11 @@ Privileges to list and view details on existing repositories and snapshots.
 +
 This privilege is not available in {serverless-full}.
 
+`monitor_stats`::
+Privileges to list and view details of stats.
++
+This privilege is not available in {serverless-full}.
+
 `monitor_text_structure`::
 All read-only operations related to the <<find-structure,find structure API>>.
 +