diff --git a/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc b/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc
index 735e1d474e0..c325406c8ee 100644
--- a/x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc
+++ b/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
diff --git a/x-pack/docs/en/rest-api/security/delete-role-mappings.asciidoc b/x-pack/docs/en/rest-api/security/delete-role-mappings.asciidoc
index 489aa944805..c5dd1aa9c90 100644
--- a/x-pack/docs/en/rest-api/security/delete-role-mappings.asciidoc
+++ b/x-pack/docs/en/rest-api/security/delete-role-mappings.asciidoc
@@ -21,7 +21,12 @@ Removes role mappings.
 ==== {api-description-title}
 
 Role mappings define which roles are assigned to each user. For more information, 
-see <<mapping-roles>>. 
+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}
diff --git a/x-pack/docs/en/rest-api/security/get-role-mappings.asciidoc b/x-pack/docs/en/rest-api/security/get-role-mappings.asciidoc
index 5243d775250..6fa79fe8a03 100644
--- a/x-pack/docs/en/rest-api/security/get-role-mappings.asciidoc
+++ b/x-pack/docs/en/rest-api/security/get-role-mappings.asciidoc
@@ -23,7 +23,12 @@ Retrieves role mappings.
 ==== {api-description-title}
 
 Role mappings define which roles are assigned to each user. For more information, 
-see <<mapping-roles>>. 
+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}
diff --git a/x-pack/docs/en/security/authorization/mapping-roles.asciidoc b/x-pack/docs/en/security/authorization/mapping-roles.asciidoc
index c202508caa3..012c8fc4ed9 100644
--- a/x-pack/docs/en/security/authorization/mapping-roles.asciidoc
+++ b/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]]