From 66a723d13497f315256f48d87950766eba18d175 Mon Sep 17 00:00:00 2001 From: Igor Motov Date: Fri, 21 Jul 2017 15:26:23 -0400 Subject: [PATCH] Docs: Add Upgrade API documentation (elastic/x-pack-elasticsearch#2063) Original commit: elastic/x-pack-elasticsearch@f5a7c9ee5d44b9c64e9286da1fdf3f801d9c76df --- docs/en/rest-api/index.asciidoc | 2 + docs/en/rest-api/migration.asciidoc | 12 ++ .../en/rest-api/migration/assistance.asciidoc | 67 +++++++++++ docs/en/rest-api/migration/upgrade.asciidoc | 108 ++++++++++++++++++ .../api/xpack.migration.get_assistance.json | 1 + .../api/xpack.migration.upgrade.json | 1 + 6 files changed, 191 insertions(+) create mode 100644 docs/en/rest-api/migration.asciidoc create mode 100644 docs/en/rest-api/migration/assistance.asciidoc create mode 100644 docs/en/rest-api/migration/upgrade.asciidoc diff --git a/docs/en/rest-api/index.asciidoc b/docs/en/rest-api/index.asciidoc index 006d22c21db..6b0cb393d07 100644 --- a/docs/en/rest-api/index.asciidoc +++ b/docs/en/rest-api/index.asciidoc @@ -12,6 +12,7 @@ directly to configure and access {xpack} features. * <> * <> * <> +* <> -- @@ -20,4 +21,5 @@ include::graph/explore.asciidoc[] include::ml-api.asciidoc[] include::security.asciidoc[] include::watcher.asciidoc[] +include::migration.asciidoc[] include::defs.asciidoc[] diff --git a/docs/en/rest-api/migration.asciidoc b/docs/en/rest-api/migration.asciidoc new file mode 100644 index 00000000000..634ebc60102 --- /dev/null +++ b/docs/en/rest-api/migration.asciidoc @@ -0,0 +1,12 @@ +[role="xpack"] +[[migration-api]] +== Migration APIs + +The migration APIs simplify upgrading {xpack} indices from one version to another. + +* <> +* <> + +include::migration/assistance.asciidoc[] +include::migration/upgrade.asciidoc[] + diff --git a/docs/en/rest-api/migration/assistance.asciidoc b/docs/en/rest-api/migration/assistance.asciidoc new file mode 100644 index 00000000000..c239156f012 --- /dev/null +++ b/docs/en/rest-api/migration/assistance.asciidoc @@ -0,0 +1,67 @@ +[role="xpack"] +[[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. + +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] +-------------------------------------------------- +GET /_xpack/migration/assistance +-------------------------------------------------- +// CONSOLE +// TEST[skip:cannot create an old index in docs test] + +A successful call returns a list of indices that need to updated or reindexed: + +[source,js] +-------------------------------------------------- +{ + "indices" : { + ".watches" : { + "action_required" : "upgrade" + }, + ".security" : { + "action_required" : "upgrade" + }, + "my_old_index": { + "action_required" : "reindex" + }, + "my_other_old_index": { + "action_required" : "reindex" + } + } +} +-------------------------------------------------- +// 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: + +[source,js] +-------------------------------------------------- +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: + +[source,js] +-------------------------------------------------- +{ + "indices" : { + "my_old_index": { + "action_required" : "reindex" + }, + "my_other_old_index": { + "action_required" : "reindex" + } + } +} +-------------------------------------------------- +// NOTCONSOLE \ No newline at end of file diff --git a/docs/en/rest-api/migration/upgrade.asciidoc b/docs/en/rest-api/migration/upgrade.asciidoc new file mode 100644 index 00000000000..f947f61477a --- /dev/null +++ b/docs/en/rest-api/migration/upgrade.asciidoc @@ -0,0 +1,108 @@ +[role="xpack"] +[[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. + +Indices need to be upgraded one at a time by submitting a POST request to the +`/_xpack/migration/upgrade/index_name` endpoint: + +[source,js] +-------------------------------------------------- +POST /_xpack/migration/upgrade/.watches +-------------------------------------------------- +// CONSOLE +// TEST[skip:cannot create an old index in docs test] + +A successful call returns the statistics about the upgrade process: + +[source,js] +-------------------------------------------------- +{ + "took" : 127, + "timed_out" : false, + "total" : 4, + "updated" : 0, + "created" : 4, + "deleted" : 0, + "batches" : 1, + "version_conflicts" : 0, + "noops" : 0, + "retries" : { + "bulk" : 0, + "search" : 0 + }, + "throttled_millis" : 0, + "failures" : [ ] +} +-------------------------------------------------- +// 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: + +[source,js] +-------------------------------------------------- +POST /_xpack/migration/upgrade/.watches?wait_for_completion=false +-------------------------------------------------- +// CONSOLE +// TEST[skip:cannot create an old index in docs test] + +This call should return the id of the upgrade process task: + +[source,js] +-------------------------------------------------- +{ + "task" : "PFvgv7T6TGumRyFF3vqTFg:1137" +} +-------------------------------------------------- +// NOTCONSOLE + +The status of the running or finished upgrade requests can be obtained using <>: + +[source,js] +-------------------------------------------------- +GET _tasks/PFvgv7T6TGumRyFF3vqTFg:1137?detailed=true +-------------------------------------------------- +// CONSOLE +// TEST[skip:cannot create an old index in docs test] + +[source,js] +-------------------------------------------------- +{ + "completed" : true, <1> + "task" : { + "node" : "PFvgv7T6TGumRyFF3vqTFg", + "id" : 1137, + "type" : "transport", + "action" : "cluster:admin/xpack/upgrade", + "description" : "", + "start_time_in_millis" : 1500650625413, + "running_time_in_nanos" : 947456819, + "cancellable" : true + }, + "response" : { <2> + "took" : 212, + "timed_out" : false, + "total" : 4, + "updated" : 0, + "created" : 4, + "deleted" : 0, + "batches" : 1, + "version_conflicts" : 0, + "noops" : 0, + "retries" : { + "bulk" : 0, + "search" : 0 + }, + "throttled_millis" : 0, + "failures" : [ ] + } +} +-------------------------------------------------- +// NOTCONSOLE + +<1> `true` in the `completed` field indicates that the upgrade request has finished, `false` means that +request is still executing + +<2> the `response` field contains the status of the upgrade request diff --git a/plugin/src/test/resources/rest-api-spec/api/xpack.migration.get_assistance.json b/plugin/src/test/resources/rest-api-spec/api/xpack.migration.get_assistance.json index f1225b565e2..46abf6741c1 100644 --- a/plugin/src/test/resources/rest-api-spec/api/xpack.migration.get_assistance.json +++ b/plugin/src/test/resources/rest-api-spec/api/xpack.migration.get_assistance.json @@ -1,5 +1,6 @@ { "xpack.migration.get_assistance": { + "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/migration-api-assistance.html", "methods": [ "GET" ], "url": { "path": "/_xpack/migration/assistance", diff --git a/plugin/src/test/resources/rest-api-spec/api/xpack.migration.upgrade.json b/plugin/src/test/resources/rest-api-spec/api/xpack.migration.upgrade.json index daa5bb084d2..d6cdff03fa6 100644 --- a/plugin/src/test/resources/rest-api-spec/api/xpack.migration.upgrade.json +++ b/plugin/src/test/resources/rest-api-spec/api/xpack.migration.upgrade.json @@ -1,5 +1,6 @@ { "xpack.migration.upgrade": { + "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/migration-api-upgrade.html", "methods": [ "POST" ], "url": { "path": "/_xpack/migration/upgrade/{index}",