diff --git a/x-pack/docs/en/rest-api/security/create-roles.asciidoc b/x-pack/docs/en/rest-api/security/create-roles.asciidoc
index 7eda4c22b0d..19802234f32 100644
--- a/x-pack/docs/en/rest-api/security/create-roles.asciidoc
+++ b/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}
diff --git a/x-pack/docs/en/rest-api/security/delete-roles.asciidoc b/x-pack/docs/en/rest-api/security/delete-roles.asciidoc
index dec674b6577..ce5906ad8e3 100644
--- a/x-pack/docs/en/rest-api/security/delete-roles.asciidoc
+++ b/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}
diff --git a/x-pack/docs/en/rest-api/security/get-roles.asciidoc b/x-pack/docs/en/rest-api/security/get-roles.asciidoc
index f014166362e..de7234697d3 100644
--- a/x-pack/docs/en/rest-api/security/get-roles.asciidoc
+++ b/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}
diff --git a/x-pack/docs/en/security/authorization/managing-roles.asciidoc b/x-pack/docs/en/security/authorization/managing-roles.asciidoc
index ee984296f08..eab8e7f573b 100644
--- a/x-pack/docs/en/security/authorization/managing-roles.asciidoc
+++ b/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]
 ==============================