Skip to content

[DOCS] Drafts docs for Upgrade Transforms API #79139

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Oct 19, 2021
Merged

[DOCS] Drafts docs for Upgrade Transforms API #79139

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
2593e5d
[DOCS] Adds docs for Upgrade Transforms API.
szabosteve Oct 14, 2021
fce1ec4
[DOCS] Fine-tunes content.
szabosteve Oct 14, 2021
2b71806
[DOCS] Addresses feedback.
szabosteve Oct 14, 2021
f453ef5
[DOCS] Clarifies permission info.
szabosteve Oct 15, 2021
0af729d
[DOCS] Rephrase description.
szabosteve Oct 18, 2021
7e5b3f5
[DOCS] Fine-tunes description.
szabosteve Oct 18, 2021
404fd2b
[DOCS] Updates description and example response.
szabosteve Oct 19, 2021
7dbbfef
[DOCS] Amends response test.
szabosteve Oct 19, 2021
1e51377
[DOCS] Fixes response.
szabosteve Oct 19, 2021
4d45871
[DOCS] Skips testing response.
szabosteve Oct 19, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/reference/transform/apis/index.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
45 changes: 37 additions & 8 deletions docs/reference/transform/apis/upgrade-transforms.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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}
Expand All @@ -22,31 +22,60 @@ 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.

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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not 100% sold regarding this statement. It is not required to make a full cluster backup prior to running this API. We want users to run upgrades often, this statement will keep them from doing so, which is the opposite of what we are aiming for.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest we add a heading "Major version upgrade" and put this content in there. The 1st sentence could start with: "For a major version upgrade, for example 7.16 to 8.0, it is recommended...".

The paragraph "If a transform upgrade step fail ..." should be moved before "Major version upgrade".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hendrikmuhs I switched the order of the second and the third paragraph and changed the first sentence to: "For a major version update – for example, from 7.16 to 8.0 –, it is recommended to...". This way we highlight that the cluster backup is only recommended in case of major version updates. However, I don't think it's necessary to add a separate heading inside the API description to segment it further. (via 404fd2b)

However, it is recommended to perform it prior to upgrading {es} to the next
major version to ensure {ctransforms} remain started.

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.

[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]
----
Expand Down