File based role definition documentation additions (#46304) (#47086)

This commit clarifies and points out that the Role management UI and
the Role management API cannot be used to manage roles that are
defined in roles.yml and that file based role management is
intended to have a small administrative scope and not handle all
possible RBAC use cases.

x-pack/docs/en/rest-api/security/create-roles.asciidoc

@@ -24,10 +24,9 @@ privilege.
 [[security-api-put-role-desc]]
 ==== {api-description-title}
 
-The role API is generally the preferred way to manage roles, rather than using
-file-based role management. For more information about the native realm, see 
-{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
-
+The role management APIs are generally the preferred way to manage roles, rather than using
+{stack-ov}/defining-roles.html#roles-management-file[file-based role management]. The create
+or update roles API cannot update roles that are defined in roles files.
 
 [[security-api-put-role-path-params]]
 ==== {api-path-parms-title}

x-pack/docs/en/rest-api/security/delete-roles.asciidoc

@@ -22,10 +22,8 @@ Removes roles in the native realm.
 [[security-api-delete-role-desc]]
 ==== {api-description-title}
 
-The Roles API is generally the preferred way to manage roles, rather than using
-file-based role management. For more information about the native realm, see 
-{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
-
+The role management APIs are generally the preferred way to manage roles, rather than using
+{stack-ov}/defining-roles.html#roles-management-file[file-based role management]. The delete roles API cannot remove roles that are defined in roles files.
 
 [[security-api-delete-role-path-params]]
 ==== {api-path-parms-title}

x-pack/docs/en/rest-api/security/get-roles.asciidoc

@@ -23,8 +23,9 @@ privilege.
 [[security-api-get-role-desc]]
 ==== {api-description-title}
 
-For more information about the native realm, see 
-{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
+The role management APIs are generally the preferred way to manage roles, rather than using
+{stack-ov}/defining-roles.html#roles-management-file[file-based role management]. The get roles
+API cannot retrieve roles that are defined in roles files.
 
 [[security-api-get-role-path-params]]
 ==== {api-path-parms-title}

x-pack/docs/en/security/authorization/managing-roles.asciidoc

@@ -214,7 +214,16 @@ _Role Management APIs_, the role found in the file will be used.
 While the _Role Management APIs_ is the preferred mechanism to define roles,
 using the `roles.yml` file becomes useful if you want to define fixed roles that
 no one (beside an administrator having physical access to the {es} nodes)
-would be able to change.
+would be able to change. Please note however, that the `roles.yml` file is provided as a
+minimal administrative function and is not intended to cover and be used
+to define roles for all use cases.
+
+[IMPORTANT]
+==============================
+You cannot view, edit, or remove any roles that are defined in `roles.yml` by
+using the <<roles-management-ui,role management UI>> or the
+<<roles-management-api,role management APIs>>.
+==============================
 
 [IMPORTANT]
 ==============================