mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 01:13:23 -04:00
[docs] Add docs for Upgrade Assistant APIs (#30330)
* [docs] Add docs for Upgrade Assistant APIs * Apply suggestions from code review Co-Authored-By: joshdover <me@joshdover.com> * Link to code tables
This commit is contained in:
Josh Dover
GitHub
parent
5e92d585c0
commit
7c49336a8d
4 changed files with 219 additions and 1 deletions
|
|
@ -34,6 +34,7 @@ NOTE: You cannot access these APIs via the Console in Kibana.
|
|||
* <<dashboard-import-api>>
|
||||
* <<logstash-configuration-management-api>>
|
||||
* <<url-shortening-api>>
|
||||
* <<upgrade-assistant-api>>
|
||||
--
|
||||
|
||||
include::api/spaces-management.asciidoc[]
|
||||
|
|
@ -42,4 +43,4 @@ include::api/saved-objects.asciidoc[]
|
|||
include::api/dashboard-import.asciidoc[]
|
||||
include::api/logstash-configuration-management.asciidoc[]
|
||||
include::api/url-shortening.asciidoc[]
|
||||
|
||||
include::api/upgrade-assistant.asciidoc[]
|
||||
|
|
|
|||
15
docs/api/upgrade-assistant.asciidoc
Normal file
15
docs/api/upgrade-assistant.asciidoc
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
[role="xpack"]
|
||||
[[upgrade-assistant-api]]
|
||||
== Upgrade Assistant API
|
||||
|
||||
experimental[This API is *experimental* and may be changed or removed completely in a future release. The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are currently experimental.]
|
||||
|
||||
The Upgrade Assistant API allows you to check the upgrade status of your Elasticsearch cluster
|
||||
and reindex indices that were created in the previous major version. The assistant helps you prepare
|
||||
for the next major version of Elasticsearch.
|
||||
|
||||
* <<upgrade-assistant-api-status>>
|
||||
* <<upgrade-assistant-api-reindexing>>
|
||||
|
||||
include::upgrade-assistant/status.asciidoc[]
|
||||
include::upgrade-assistant/reindexing.asciidoc[]
|
||||
154
docs/api/upgrade-assistant/reindexing.asciidoc
Normal file
154
docs/api/upgrade-assistant/reindexing.asciidoc
Normal file
|
|
@ -0,0 +1,154 @@
|
|||
[[upgrade-assistant-api-reindexing]]
|
||||
=== Reindex API
|
||||
|
||||
experimental[This API is *experimental* and may be changed or removed completely in a future release. The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are currently experimental.]
|
||||
|
||||
When checking the upgrade status, some indices will have the `reindex` paramaeter set to `true`. You can use this Reindexing API to reindex these indices.
|
||||
|
||||
==== Start or resume a reindex
|
||||
|
||||
===== Request
|
||||
|
||||
To start a new reindex or resume a paused reindex, submit a POST request to the `/api/upgrade_assistant/reindex/<indexName>` endpoint:
|
||||
|
||||
Note: You cannot access this endpoint via the Console in Kibana.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST /api/upgrade_assistant/reindex/myIndex
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
===== Response
|
||||
|
||||
A successful call returns a response code of `200` and a response body
|
||||
containing a JSON structure similar to the following example:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"indexName": ".ml-state",
|
||||
"newIndexName": ".reindexed-v7-ml-state",
|
||||
"status": 0,
|
||||
"lastCompletedStep": 0,
|
||||
"reindexTaskId": null,
|
||||
"reindexTaskPercComplete": null,
|
||||
"errorMessage": null
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
See the next section for an explanation of each field.
|
||||
|
||||
==== Check the status of a reindex
|
||||
|
||||
===== Request
|
||||
|
||||
Once a reindex is started, you can check the status of the reindex operation by submitting a GET request to the `/api/upgrade_assistant/reindex/<indexName>` endpoint:
|
||||
|
||||
Note: You cannot access this endpoint via the Console in Kibana.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /api/upgrade_assistant/reindex/myIndex
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
===== Response
|
||||
|
||||
A successful call returns a response code of `200` and a response body
|
||||
containing a JSON structure similar to the following example:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"reindexOp": {
|
||||
"indexName": ".ml-state",
|
||||
"newIndexName": ".reindexed-v7-ml-state", <1>
|
||||
"status": 0, <2>
|
||||
"lastCompletedStep": 40, <3>
|
||||
"reindexTaskId": "QprwvTMzRQ2MLWOW22oQ4Q:11819", <4>
|
||||
"reindexTaskPercComplete": 0.3, <5>
|
||||
"errorMessage": null <6>
|
||||
},
|
||||
"warnings": [], <7>
|
||||
"hasRequiredPrivileges": true <8>
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
<1> Name of the new index that is being created.
|
||||
<2> Current status of the reindex. See the <<status-code,status code table>> for details.
|
||||
<3> Last successfully completed step of the reindex. See the <<step-code,step code table>> table for details.
|
||||
<4> Task ID of the reindex task in Elasticsearch. Only present if reindexing has started.
|
||||
<5> Percentage of how far the reindexing task in Elasticsearch has progressed, in decimal from from 0 to 1.
|
||||
<6> Error that caused the reindex to fail, if it failed.
|
||||
<7> An array of any warning codes explaining what changes are required for this reindex. See the <<warning-code,warning code table>> for details.
|
||||
<8> Whether or not the current user has required privileges to reindex this index. Returns `true` if Security is not available or disabled.
|
||||
|
||||
[[status-code]]
|
||||
===== Status code
|
||||
|
||||
The `status` field corresponds to these statuses:
|
||||
|
||||
[horizontal]
|
||||
0:: in progress
|
||||
1:: completed
|
||||
2:: failed
|
||||
3:: paused
|
||||
4:: cancelled
|
||||
|
||||
[[step-code]]
|
||||
===== Step code
|
||||
|
||||
The `lastCompletedStep` field corresponds to these steps:
|
||||
|
||||
[horizontal]
|
||||
0:: The reindex operation has been created in Kibana.
|
||||
10:: Index group services stopped. Only applies to some system indices.
|
||||
20:: index set to readonly
|
||||
30:: The new destination index has been created.
|
||||
40:: The reindex task in Elasticsearch has started.
|
||||
50:: The reindex task in Elasticsearch has completed.
|
||||
60:: Aliases have been created to point to the new index, and the old index has been deleted.
|
||||
70:: Index group services have been resumed. Only applies to some system indices.
|
||||
|
||||
[[warning-code]]
|
||||
===== Warning code
|
||||
|
||||
The `warnings` field corresponds to an array of integers for these warnings:
|
||||
|
||||
[horizontal]
|
||||
0:: The `_all` meta field will be removed.
|
||||
1:: Any coerced boolean values will be converted in the source document (example: `yes`, `1`, `off`).
|
||||
2:: Documents will be converted to support Elastic Common Schema. Only applies to APM indices created in 6.x.
|
||||
|
||||
===== Paused reindexes
|
||||
|
||||
If the Kibana node that started the reindex is shutdown or restarted, the reindex will go into a paused state after some time.
|
||||
To resume the reindex, you must submit a new POST request to the `/api/upgrade_assistant/reindex/<indexName>` endpoint.
|
||||
|
||||
==== Cancel a reindex
|
||||
|
||||
===== Request
|
||||
|
||||
You can cancel reindexes that are waiting for the Elasticsearch reindex task to complete (`lastCompletedStep` set to `40`).
|
||||
To cancel a reindex, submit a POST request to the `/api/upgrade_assistant/reindex/<indexName>/cancel` endpoint:
|
||||
|
||||
Note: You cannot access this endpoint via the Console in Kibana.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
POST /api/upgrade_assistant/reindex/myIndex/cancel
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
===== Response
|
||||
|
||||
A successful call returns a response code of `200` and a response body
|
||||
containing a JSON structure similar to the following example:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
--------------------------------------------------
|
||||
48
docs/api/upgrade-assistant/status.asciidoc
Normal file
48
docs/api/upgrade-assistant/status.asciidoc
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
[[upgrade-assistant-api-status]]
|
||||
=== Upgrade Readiness Status
|
||||
|
||||
experimental[This API is *experimental* and may be changed or removed completely in a future release. The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are currently experimental.]
|
||||
|
||||
==== Request
|
||||
|
||||
To check the status of your cluster, submit a GET request to the `/api/upgrade_assistant/status` endpoint:
|
||||
|
||||
Note: You cannot access this endpoint via the Console in Kibana.
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
GET /api/upgrade_assistant/status
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
==== Response
|
||||
|
||||
A successful call returns a response code of `200` and a response body
|
||||
containing a JSON structure similar to the following example:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
{
|
||||
"readyForUpgrade": false,
|
||||
"cluster": [
|
||||
{
|
||||
"message": "Cluster deprecated issue",
|
||||
"details": "...",
|
||||
"level": "warning",
|
||||
"url": "https://docs.elastic.co/..."
|
||||
}
|
||||
],
|
||||
"indices": [
|
||||
{
|
||||
"message": "Index was created before 6.0",
|
||||
"details": "...",
|
||||
"index": "myIndex",
|
||||
"level": "critical",
|
||||
"reindex": true, <1>
|
||||
"url": "https://docs.elastic.co/..."
|
||||
}
|
||||
]
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
<1> You can fix indices with the `reindex` attribute set to `true` using the <<upgrade-assistant-api-reindexing>>.
|
||||
Loading…
Add table
Add a link
Reference in a new issue