[DOCS] Drafts docs for Upgrade Transforms API (#79139)

Author: szabosteve

docs/reference/transform/apis/index.asciidoc

@@ -13,5 +13,6 @@ include::preview-transform.asciidoc[leveloffset=+2]
 include::start-transform.asciidoc[leveloffset=+2]
 //STOP
 include::stop-transform.asciidoc[leveloffset=+2]
-//UPDATE
-include::update-transform.asciidoc[leveloffset=+2]
+//UPDATE-UPGRADE
+include::update-transform.asciidoc[leveloffset=+2]
+include::upgrade-transforms.asciidoc[leveloffset=+2]

docs/reference/transform/apis/upgrade-transforms.asciidoc

@@ -1,14 +1,14 @@
 [role="xpack"]
 [testenv="basic"]
 [[upgrade-transforms]]
-= Upgrade {transform} API
+= Upgrade {transforms} API
 
 [subs="attributes"]
 ++++
-<titleabbrev>Upgrade {transform}</titleabbrev>
+<titleabbrev>Upgrade {transforms}</titleabbrev>
 ++++
 
-Upgrades all {transform}s.
+Upgrades all {transforms}.
 
 [[upgrade-transforms-request]]
 == {api-request-title}
@@ -22,36 +22,68 @@ Requires the following privileges:
 
 * cluster: `manage_transform` (the `transform_admin` built-in role grants this
   privilege)
-* source indices: `read`, `view_index_metadata`
-* destination index: `read`, `index`.
 
 
 [[upgrade-transforms-desc]]
 == {api-description-title}
 
-This API upgrades all existing {transform}s.
+{transforms-cap} are compatible across minor versions and between supported 
+major versions. However, over time, the format of {transform} configuration 
+information may change. This API identifies {transforms} which have a legacy 
+configuration format and upgrades them to the latest version; including clean up 
+of the internal data structures that store {transform} state and checkpoints. 
+{transform-cap} upgrade does not effect the source and destination indices.
+
+If a {transform} upgrade step fails, the upgrade stops, and an error is returned 
+about the underlying issue. Resolve the issue then re-run the process again. A 
+summary is returned when the upgrade is finished.
+
+For a major version update – for example, from 7.16 to 8.0 –, it is recommended 
+to have a recent cluster backup prior to performing a {transform} upgrade which 
+can be run either before or after an {es} upgrade. However, it is recommended to 
+perform it before upgrading {es} to the next major version to ensure 
+{ctransforms} remain running.
+
+
+[IMPORTANT]
+====
+
+* When {es} {security-features} are enabled, your {transform} remembers the 
+roles of the user who created or updated it last. In contrast to 
+<<update-transform,update transform>>, a {transform} upgrade does not change the 
+stored roles, therefore the role used to read source data and write to the 
+destination index remains unchanged.
+
+====
+
 
 [[upgrade-transforms-query-parms]]
 == {api-query-parms-title}
 
 `dry_run`::
-  (Optional, Boolean) When `true`, only checks for updates but does not execute them.
+  (Optional, Boolean) When `true`, only checks for updates but does not execute 
+  them. Defaults to `false`.
+
 
 [[upgrade-transforms-example]]
 == {api-examples-title}
 
+To upgrade the legacy {transforms} to the latest configuration format, perform 
+the following API call:
+
 [source,console]
 --------------------------------------------------
 POST _transform/_upgrade
 --------------------------------------------------
 // TEST[setup:simple_kibana_continuous_pivot]
 
-When all {transform}s are upgraded, you receive a summary:
+When all {transforms} are upgraded, you receive a summary:
 
 [source,console-result]
 ----
 {
+  "updated": 2,
   "no_action": 1
 }
 ----
-// TESTRESPONSE[s/"no_action" : 1/"no_action" : $body.no_action/]
+// TESTRESPONSE[skip:TBD]