honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[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 2017-09-11 14:02:23 -07:00 committed by GitHub
parent 90c6b93897
commit 26148c91fe
3 changed files with 123 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
docs/en/rest-api/migration/assistance.asciidoc
View File

@ -2,11 +2,35 @@
[[migration-api-assistance]]
=== Migration Assistance API
The Migration Assistance API analyzes existing indices in the cluster and returns the information
about indices that require some changes before the cluster can be upgraded to the next major version.
The Migration Assistance API analyzes existing indices in the cluster and
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
`/_xpack/migration/assistance` endpoint:
[float]
==== 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]
--------------------------------------------------
@ -38,8 +62,8 @@ A successful call returns a list of indices that need to updated or reindexed:
--------------------------------------------------
// NOTCONSOLE
To check a particular index or set of indices, specify this index name or mask as the last part of the
`/_xpack/migration/assistance/index_name` endpoint:
To check a particular index or set of indices, specify this index name or mask
as the last part of the `/_xpack/migration/assistance/index_name` endpoint:
[source,js]
--------------------------------------------------
@ -48,8 +72,8 @@ GET /_xpack/migration/assistance/my_*
// CONSOLE
// 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
on the endpoint:
A successful call returns a list of indices that needs to updated or reindexed
and match the index specified on the endpoint:
[source,js]
--------------------------------------------------

69
docs/en/rest-api/migration/deprecation.asciidoc
View File

@ -2,10 +2,36 @@
[[migration-api-deprecation]]
== Deprecation Info APIs
The deprecation API is to be used to retrieve information about different cluster, node, and index level
settings that use deprecated features that will be removed or changed in the next major version.
The deprecation API is to be used to retrieve information about different
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]
--------------------------------------------------
@ -43,8 +69,9 @@ Example response:
--------------------------------------------------
// NOTCONSOLE
The response you will receive will break down all the specific forward-incompatible settings that your
cluster should resolve before upgrading. Any offending setting will be represented as a deprecation warning.
The response breaks down all the specific forward-incompatible settings that you
should resolve before upgrading your cluster. Any offending settings are
represented as a deprecation warning.
The following is an example deprecation warning:
@ -59,25 +86,31 @@ The following is an example deprecation warning:
--------------------------------------------------
// 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
|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
|critical | You cannot upgrade without fixing this problem
|none | Everything is good.
|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.
|critical | You cannot upgrade without fixing this problem.
|=======
`message` and the optional `details` provide descriptive information about the deprecation warning, while the `url`
property provides a link to the Breaking Changes Documentation, where more information about this change can be found.
The `message` property and the optional `details` property provide descriptive
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
the `cluster_settings` key. Similarly, any node-level warnings will be found under `node_settings`.
Since only a select subset of your nodes may incorporate these settings, it is important to read the
`details` section for more information about which nodes are to be updated. Index warnings are
sectioned off per index and can be filtered using an index-pattern in the query.
Any cluster-level deprecation warnings can be found under the `cluster_settings`
key. Similarly, any node-level warnings are found under `node_settings`. Since
only a select subset of your nodes might incorporate these settings, it is
important to read the `details` section for more information about which nodes
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]
--------------------------------------------------

48
docs/en/rest-api/migration/upgrade.asciidoc
View File

@ -2,10 +2,39 @@
[[migration-api-upgrade]]
=== 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
`/_xpack/migration/upgrade/index_name` endpoint:
[float]
==== 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]
--------------------------------------------------
@ -38,8 +67,8 @@ A successful call returns the statistics about the upgrade process:
--------------------------------------------------
// NOTCONSOLE
By default, the upgrade call blocks until the upgrade process is finished. For large indices the upgrade can be
performed asynchronously by specifying `wait_for_completion=false` parameter:
The following example upgrades a large index asynchronously by specifying the
`wait_for_completion` parameter:
[source,js]
--------------------------------------------------
@ -58,7 +87,8 @@ This call should return the id of the upgrade process task:
--------------------------------------------------
// 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]
--------------------------------------------------
@ -102,7 +132,7 @@ GET _tasks/PFvgv7T6TGumRyFF3vqTFg:1137?detailed=true
--------------------------------------------------
// NOTCONSOLE
<1> `true` in the `completed` field indicates that the upgrade request has finished, `false` means that
request is still executing
<1> If the `completed` field value is `true`, the upgrade request has finished.
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.