diff --git a/docs/api.asciidoc b/docs/api.asciidoc index ab9134c27719d9..01255386455207 100644 --- a/docs/api.asciidoc +++ b/docs/api.asciidoc @@ -34,6 +34,7 @@ NOTE: You cannot access these APIs via the Console in Kibana. * <> * <> * <> +* <> -- 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[] diff --git a/docs/api/upgrade-assistant.asciidoc b/docs/api/upgrade-assistant.asciidoc new file mode 100644 index 00000000000000..5779dc0ec73b06 --- /dev/null +++ b/docs/api/upgrade-assistant.asciidoc @@ -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. + +* <> +* <> + +include::upgrade-assistant/status.asciidoc[] +include::upgrade-assistant/reindexing.asciidoc[] diff --git a/docs/api/upgrade-assistant/reindexing.asciidoc b/docs/api/upgrade-assistant/reindexing.asciidoc new file mode 100644 index 00000000000000..774fb8439fedf4 --- /dev/null +++ b/docs/api/upgrade-assistant/reindexing.asciidoc @@ -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/` 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/` 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 <> for details. +<3> Last successfully completed step of the reindex. See the <> 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 <> 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/` 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//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 +} +-------------------------------------------------- diff --git a/docs/api/upgrade-assistant/status.asciidoc b/docs/api/upgrade-assistant/status.asciidoc new file mode 100644 index 00000000000000..21781472f7c679 --- /dev/null +++ b/docs/api/upgrade-assistant/status.asciidoc @@ -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 <>.