From 2eaf5e1c25b4438fbfae2f7648291498accf912c Mon Sep 17 00:00:00 2001
From: Albert Zaharovits <albert.zaharovits@elastic.co>
Date: Thu, 23 Jul 2020 19:49:23 +0300
Subject: [PATCH] [DOCS] Mapping updates are deprecated for ingestion
 privileges (#60024)

This PR contains the deprecation notice that `create`, `create_doc`, `index` and
`write` ingest privileges do not permit mapping updates in version 8. It also
updates the docs description of said privileges.

This should've been part of #58784
---
 docs/reference/migration/migrate_7_9.asciidoc | 34 +++++++++++++++++++
 .../authorization/privileges.asciidoc         | 33 +++++++++++++-----
 2 files changed, 59 insertions(+), 8 deletions(-)

diff --git a/docs/reference/migration/migrate_7_9.asciidoc b/docs/reference/migration/migrate_7_9.asciidoc
index c58b1b10a7631..03a4490e1a6c1 100644
--- a/docs/reference/migration/migrate_7_9.asciidoc
+++ b/docs/reference/migration/migrate_7_9.asciidoc
@@ -70,6 +70,40 @@ context.  For example, for the `processor_conditional` context, use
 
 ====
 
+[discrete]
+[[deprecate_mapping_updates_for_ingest_privileges]]
+.Mapping actions have been deprecated for the `create_doc`, `create`, `index` and `write` privileges.
+[%collapsible]
+====
+*Details* +
+In {es} 8.0.0, the following privileges will no longer allow users to
+explicitly update the mapping of an index:
+
+* `create_doc`
+* `create`
+* `index`
+* `write`
+
+Additionally, in {es} 8.0.0, the following privileges will no longer allow users to
+{ref}/dynamic-mapping.html[dynamically update the mapping] of an index 
+during indexing or ingest:
+
+* `create_doc`
+* `create`
+* `index`
+
+These privileges will continue to allow mapping actions on indices (but not on data streams) until
+{es} 8.0.0. However, deprecation warnings will be returned.
+
+*Impact* +
+To allow users to explicitly update the mapping of an index,
+grant the `manage` privilege.
+
+To dynamically update the mapping of an index during indexing or
+ingest, grant the `auto_configure` privilege and use index templates. This lets
+you dynamically update the index mapping based on the template's mapping configuration.
+====
+
 [discrete]
 [[breaking_79_settings_changes]]
 === Settings changes
diff --git a/x-pack/docs/en/security/authorization/privileges.asciidoc b/x-pack/docs/en/security/authorization/privileges.asciidoc
index 4a98ea0ff4e92..42f57f2d7692f 100644
--- a/x-pack/docs/en/security/authorization/privileges.asciidoc
+++ b/x-pack/docs/en/security/authorization/privileges.asciidoc
@@ -162,8 +162,13 @@ bulk request on an index or data stream that contains new fields that may
 be mapped rather than an explicit <<indices-put-mapping,put mapping>> request.
 
 `create`::
-Privilege to index documents. Also grants access to the update mapping
-action.
+Privilege to index documents, allowing overwriting any existing document, but
+not permitting updating one.
++
+deprecated:[7.9] Also grants the permission to update the index mapping (but not
+the data stream mapping), using the update mapping action, or relying on
+{ref}/dynamic-mapping.html[dynamic mappings]. In the next major release,
+this privilege will not grant any mapping update permission.
 +
 --
 NOTE: This privilege does not restrict the index operation to the creation
@@ -174,8 +179,13 @@ privilege for an alternative.
 --
 
 `create_doc`::
-Privilege to index documents. Also grants access to the update mapping action.
-However, it does not enable a user to update existing documents.
+Privilege to index new documents, without allowing overwriting or updating
+existing ones.
++
+deprecated:[7.9] Also grants the permission to update the index mapping (but not
+the data stream mapping), using the update mapping action, or relying on
+{ref}/dynamic-mapping.html[dynamic mappings]. In the next major release,
+this privilege will not grant any mapping update permission.
 +
 --
 [NOTE]
@@ -205,8 +215,12 @@ Privilege to delete documents.
 Privilege to delete an index.
 
 `index`::
-Privilege to index and update documents. Also grants access to the update
-mapping action.
+Privilege to index (overwriting included) and update documents.
++
+deprecated:[7.9] Also grants the permission to update the index mapping (but not
+the data stream mapping), using the update mapping action, or relying on
+{ref}/dynamic-mapping.html[dynamic mappings]. In the next major release,
+this privilege will not grant any mapping update permission.
 
 `maintenance`::
 Permits refresh, flush, synced flush and force merge index administration operations.
@@ -252,8 +266,11 @@ privilege is primarily available for use by {kib} users.
 `write`::
 Privilege to perform all write operations to documents, which includes the
 permission to index, update, and delete documents as well as performing bulk
-operations. Also grants access to the update mapping action.
-
+operations, and allows the {ref}/dynamic-mapping.html[dynamic mapping updates]
+as a result of these.
++
+deprecated:[7.9] Until the next major release, this also grants access to the
+update mapping action, but only on indices, not on data streams.
 
 ==== Run as privilege