File based role mappings vs the role mapping APIs (#47015) (#47978)

Make clear in the docs that the role mapping APIs is the preferred
way to manage role mappings and that the role mappings that are
defined in files cannot be viewed or managed with the APIs

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

@@ -24,8 +24,12 @@ Creates and updates role mappings.
 ==== {api-description-title}
 
 Role mappings define which roles are assigned to each user. Each mapping has 
-_rules_ that identify users and a list of _roles_ that are
-granted to those users.  
+_rules_ that identify users and a list of _roles_ that are granted to those users.
+
+The role mapping APIs are generally the preferred way to manage role mappings
+rather than using {stack-ov}/mapping-roles.html#mapping-roles-file[role mapping files].
+The create or update role mappings API cannot update role mappings that are defined
+in role mapping files.
 
 NOTE: This API does not create roles. Rather, it maps users to existing roles.
 Roles can be created by using <<security-api-roles, Role Management APIs>> or

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

@@ -23,6 +23,11 @@ Removes role mappings.
 Role mappings define which roles are assigned to each user. For more information, 
 see <<mapping-roles>>.
 
+The role mapping APIs are generally the preferred way to manage role mappings
+rather than using <<mapping-roles-file,role mapping files>>.
+The delete role mappings API cannot remove role mappings that are defined
+in role mapping files.
+
 [[security-api-delete-role-mapping-path-params]]
 ==== {api-path-parms-title}
 

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

@@ -25,6 +25,11 @@ Retrieves role mappings.
 Role mappings define which roles are assigned to each user. For more information, 
 see <<mapping-roles>>.
 
+The role mapping APIs are generally the preferred way to manage role mappings
+rather than using <<mapping-roles-file,role mapping files>>.
+The get role mappings API cannot retrieve role mappings that are defined
+in role mapping files.
+
 [[security-api-get-role-mapping-path-params]]
 ==== {api-path-parms-title}
 

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

@@ -66,6 +66,24 @@ You can change this default behavior by changing the
 this is a common setting in Elasticsearch, changing its value might effect other
 schedules in the system.
 
+While the _role mapping APIs_ is he preferred way to manage role mappings, using
+the `role_mappings.yml` file becomes useful in a couple of use cases: 
+
+. If you want to define fixed role mappings that no one (besides an administrator 
+with physical access to the {es} nodes) would be able to change.
+
+. If cluster administration depends on users from external realms and these users
+need to have their roles mapped to them even when the cluster is RED. For instance
+an administrator that authenticates via LDAP or PKI and gets assigned an
+administrator role so that they can perform corrective actions.
+
+Please note however, that the role_mappings.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 the role
+mapping files by using the the role mapping APIs. 
+
 ==== Realm specific details
 [float]
 [[ldap-role-mapping]]