[DOCS] Format X-Pack migration APIs (elastic/x-pack-elasticsearch#2378)
Original commit: elastic/x-pack-elasticsearch@502d77b975
This commit is contained in:
Lisa Cawley
GitHub
parent
90c6b93897
commit
26148c91fe
|
|
@ -2,11 +2,35 @@
|
||||||
[[migration-api-assistance]]
|
[[migration-api-assistance]]
|
||||||
=== Migration Assistance API
|
=== Migration Assistance API
|
||||||
|
|
||||||
The Migration Assistance API analyzes existing indices in the cluster and returns the information
|
The Migration Assistance API analyzes existing indices in the cluster and
|
||||||
about indices that require some changes before the cluster can be upgraded to the next major version.
|
returns the information about indices that require some changes before the
|
||||||
|
cluster can be upgraded to the next major version.
|
||||||
|
|
||||||
To see a list of indices that needs to be upgraded or reindexed, submit a GET request to the
|
[float]
|
||||||
`/_xpack/migration/assistance` endpoint:
|
==== Request
|
||||||
|
|
||||||
|
`GET /_xpack/migration/assistance` +
|
||||||
|
|
||||||
|
`GET /_xpack/migration/assistance/<index_name>`
|
||||||
|
|
||||||
|
//==== Description
|
||||||
|
|
||||||
|
[float]
|
||||||
|
==== Path Parameters
|
||||||
|
|
||||||
|
`index_name`::
|
||||||
|
(string) Identifier for the index. It can be an index name or a wildcard
|
||||||
|
expression.
|
||||||
|
|
||||||
|
//==== Query Parameters
|
||||||
|
|
||||||
|
//==== Authorization
|
||||||
|
|
||||||
|
[float]
|
||||||
|
==== Examples
|
||||||
|
|
||||||
|
To see a list of indices that needs to be upgraded or reindexed, submit a GET
|
||||||
|
request to the `/_xpack/migration/assistance` endpoint:
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
|
@ -38,8 +62,8 @@ A successful call returns a list of indices that need to updated or reindexed:
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
// NOTCONSOLE
|
// NOTCONSOLE
|
||||||
|
|
||||||
To check a particular index or set of indices, specify this index name or mask as the last part of the
|
To check a particular index or set of indices, specify this index name or mask
|
||||||
`/_xpack/migration/assistance/index_name` endpoint:
|
as the last part of the `/_xpack/migration/assistance/index_name` endpoint:
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
|
@ -48,8 +72,8 @@ GET /_xpack/migration/assistance/my_*
|
||||||
// CONSOLE
|
// CONSOLE
|
||||||
// TEST[skip:cannot create an old index in docs test]
|
// TEST[skip:cannot create an old index in docs test]
|
||||||
|
|
||||||
A successful call returns a list of indices that needs to updated or reindexed and match the index specified
|
A successful call returns a list of indices that needs to updated or reindexed
|
||||||
on the endpoint:
|
and match the index specified on the endpoint:
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
|
|
||||||
|
|
@ -2,10 +2,36 @@
|
||||||
[[migration-api-deprecation]]
|
[[migration-api-deprecation]]
|
||||||
== Deprecation Info APIs
|
== Deprecation Info APIs
|
||||||
|
|
||||||
The deprecation API is to be used to retrieve information about different cluster, node, and index level
|
The deprecation API is to be used to retrieve information about different
|
||||||
settings that use deprecated features that will be removed or changed in the next major version.
|
cluster, node, and index level settings that use deprecated features that will
|
||||||
|
be removed or changed in the next major version.
|
||||||
|
|
||||||
To see the list of offenders in your cluster, submit a GET request to the `_xpack/migration/deprecations` endpoint:
|
[float]
|
||||||
|
=== Request
|
||||||
|
|
||||||
|
`GET /_xpack/migration/deprecations` +
|
||||||
|
|
||||||
|
`GET /<index_name>/_xpack/migration/deprecations`
|
||||||
|
|
||||||
|
//=== Description
|
||||||
|
|
||||||
|
[float]
|
||||||
|
=== Path Parameters
|
||||||
|
|
||||||
|
`index_name`::
|
||||||
|
(string) Identifier for the index. It can be an index name or a wildcard
|
||||||
|
expression. When you specify this parameter, only index-level deprecations for
|
||||||
|
the specified indices are returned.
|
||||||
|
|
||||||
|
//=== Query Parameters
|
||||||
|
|
||||||
|
//=== Authorization
|
||||||
|
|
||||||
|
[float]
|
||||||
|
=== Examples
|
||||||
|
|
||||||
|
To see the list of offenders in your cluster, submit a GET request to the
|
||||||
|
`_xpack/migration/deprecations` endpoint:
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
|
@ -43,8 +69,9 @@ Example response:
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
// NOTCONSOLE
|
// NOTCONSOLE
|
||||||
|
|
||||||
The response you will receive will break down all the specific forward-incompatible settings that your
|
The response breaks down all the specific forward-incompatible settings that you
|
||||||
cluster should resolve before upgrading. Any offending setting will be represented as a deprecation warning.
|
should resolve before upgrading your cluster. Any offending settings are
|
||||||
|
represented as a deprecation warning.
|
||||||
|
|
||||||
The following is an example deprecation warning:
|
The following is an example deprecation warning:
|
||||||
|
|
||||||
|
|
@ -59,25 +86,31 @@ The following is an example deprecation warning:
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
// NOTCONSOLE
|
// NOTCONSOLE
|
||||||
|
|
||||||
As is shown, there is a `level` property that describes how significant the issue may be.
|
As is shown, there is a `level` property that describes the significance of the
|
||||||
|
issue.
|
||||||
|
|
||||||
|=======
|
|=======
|
||||||
|none | everything is good
|
|none | Everything is good.
|
||||||
|info | An advisory note that something has changed. No action needed
|
|info | An advisory note that something has changed. No action needed.
|
||||||
|warning | You can upgrade directly, but you are using deprecated functionality which will not be available in the next major version
|
|warning | You can upgrade directly, but you are using deprecated functionality
|
||||||
|critical | You cannot upgrade without fixing this problem
|
which will not be available in the next major version.
|
||||||
|
|critical | You cannot upgrade without fixing this problem.
|
||||||
|=======
|
|=======
|
||||||
|
|
||||||
`message` and the optional `details` provide descriptive information about the deprecation warning, while the `url`
|
The `message` property and the optional `details` property provide descriptive
|
||||||
property provides a link to the Breaking Changes Documentation, where more information about this change can be found.
|
information about the deprecation warning. The `url` property provides a link to
|
||||||
|
the Breaking Changes Documentation, where you can find more information about
|
||||||
|
this change.
|
||||||
|
|
||||||
Any cluster-level deprecation warnings can be found under
|
Any cluster-level deprecation warnings can be found under the `cluster_settings`
|
||||||
the `cluster_settings` key. Similarly, any node-level warnings will be found under `node_settings`.
|
key. Similarly, any node-level warnings are found under `node_settings`. Since
|
||||||
Since only a select subset of your nodes may incorporate these settings, it is important to read the
|
only a select subset of your nodes might incorporate these settings, it is
|
||||||
`details` section for more information about which nodes are to be updated. Index warnings are
|
important to read the `details` section for more information about which nodes
|
||||||
sectioned off per index and can be filtered using an index-pattern in the query.
|
are affected. Index warnings are sectioned off per index and can be filtered
|
||||||
|
using an index-pattern in the query.
|
||||||
|
|
||||||
Example request that only shows index-level deprecations of all `logstash-*` indices:
|
The following example request shows only index-level deprecations of all
|
||||||
|
`logstash-*` indices:
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
|
|
||||||
|
|
@ -2,10 +2,39 @@
|
||||||
[[migration-api-upgrade]]
|
[[migration-api-upgrade]]
|
||||||
=== Migration Upgrade API
|
=== Migration Upgrade API
|
||||||
|
|
||||||
The Migration Upgrade API performs the upgrade of internal indices to make them compatible with the next major version.
|
The Migration Upgrade API performs the upgrade of internal indices to make them
|
||||||
|
compatible with the next major version.
|
||||||
|
|
||||||
Indices need to be upgraded one at a time by submitting a POST request to the
|
[float]
|
||||||
`/_xpack/migration/upgrade/index_name` endpoint:
|
==== Request
|
||||||
|
|
||||||
|
`POST /_xpack/migration/upgrade/<index_name>`
|
||||||
|
|
||||||
|
[float]
|
||||||
|
==== Description
|
||||||
|
|
||||||
|
Indices must be upgraded one at a time.
|
||||||
|
|
||||||
|
[float]
|
||||||
|
==== Path Parameters
|
||||||
|
|
||||||
|
`index_name`::
|
||||||
|
(string) Identifier for the index.
|
||||||
|
|
||||||
|
`wait_for_completion`::
|
||||||
|
(boolean) Defines whether the upgrade call blocks until the upgrade process is
|
||||||
|
finished. The default value is `true`. If set to `false`, the upgrade can be
|
||||||
|
performed asynchronously.
|
||||||
|
|
||||||
|
//==== Query Parameters
|
||||||
|
|
||||||
|
//==== Authorization
|
||||||
|
|
||||||
|
[float]
|
||||||
|
==== Examples
|
||||||
|
|
||||||
|
The following example submits a POST request to the
|
||||||
|
`/_xpack/migration/upgrade/<index_name>` endpoint:
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
|
@ -38,8 +67,8 @@ A successful call returns the statistics about the upgrade process:
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
// NOTCONSOLE
|
// NOTCONSOLE
|
||||||
|
|
||||||
By default, the upgrade call blocks until the upgrade process is finished. For large indices the upgrade can be
|
The following example upgrades a large index asynchronously by specifying the
|
||||||
performed asynchronously by specifying `wait_for_completion=false` parameter:
|
`wait_for_completion` parameter:
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
|
@ -58,7 +87,8 @@ This call should return the id of the upgrade process task:
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
// NOTCONSOLE
|
// NOTCONSOLE
|
||||||
|
|
||||||
The status of the running or finished upgrade requests can be obtained using <<tasks,Task API>>:
|
The status of the running or finished upgrade requests can be obtained by using
|
||||||
|
the <<tasks,Task API>>:
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
|
@ -102,7 +132,7 @@ GET _tasks/PFvgv7T6TGumRyFF3vqTFg:1137?detailed=true
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
// NOTCONSOLE
|
// NOTCONSOLE
|
||||||
|
|
||||||
<1> `true` in the `completed` field indicates that the upgrade request has finished, `false` means that
|
<1> If the `completed` field value is `true`, the upgrade request has finished.
|
||||||
request is still executing
|
If it is `false`, the request is still running.
|
||||||
|
|
||||||
<2> the `response` field contains the status of the upgrade request
|
<2> The `response` field contains the status of the upgrade request.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue