From 129b031df1a7e1371cfe0c4ba3a1aec755f1b6db Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 6 Mar 2019 17:24:39 -0800 Subject: [PATCH 1/5] [DOCS] Clarifies when to reindex internal indices --- .../install-upgrade/upgrading-stack.asciidoc | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/en/install-upgrade/upgrading-stack.asciidoc b/docs/en/install-upgrade/upgrading-stack.asciidoc index 2a44604f7..5bef39511 100644 --- a/docs/en/install-upgrade/upgrading-stack.asciidoc +++ b/docs/en/install-upgrade/upgrading-stack.asciidoc @@ -217,21 +217,20 @@ index as alias for the new index and delete the 2.x index. [[upgrade-internal-indices]] ==== Upgrading internal indices for {major-version} -The format used for the internal indices used by Kibana and {xpack} has -changed in {major-version}. Before you can run Kibana and {xpack} in {version}, -these indices must be upgraded to the new format. If you are upgrading from a -version prior to 5.6, you must upgrade them after after installing -Elasticsearch {version}. - -To get a list of the indices that need to be upgraded, install {xpack} and use -the {ref}/migration-api-assistance.html[`_migration/assistance` API]: - -[source,json] ----------------------------------------------------------- -GET /_migration/assistance ----------------------------------------------------------- -// CONSOLE - +{es} can read indices that were created in the *previous major version*. Older +indices must be reindexed or deleted. For example, {es} {major-version} can use +indices created in {es} {prev-major-version}, but not those created in earlier +versions. This restriction also applies to the internal indices that are used by +Kibana and the {xpack} features. Therefore, before you can use Kibana and +{xpack} features in {version}, you must upgrade the internal indices to a +compatible index structure. If you are upgrading from a version prior to +{prev-major-version}, you must upgrade to the most recent version of +{prev-major-version} first. Then you can use the {kib} Upgrade Assistant or +equivalent {ref}/migration-api-assistance.html[`_migration/assistance` API] to +check whether you need to upgrade the internal indices. + +//// +//TBD To upgrade the `.security` index: . On a single node, add a temporary superuser account to the `file` realm. @@ -254,6 +253,7 @@ internal indices using the `_migration/upgrade` API. TIP: Once you upgrade the `.kibana` index, you can run Kibana and use the {xpack} Reindex Helper UI to upgrade the other indices. +//// [[upgrade-elastic-stack-for-elastic-cloud]] === Upgrading on Elastic Cloud From b5078ffa43d0fe98c4d35ca261d16325c9add996 Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 7 Mar 2019 12:49:58 -0800 Subject: [PATCH 2/5] [DOCS] Reformats file realm tip --- docs/en/install-upgrade/index.asciidoc | 2 +- .../install-upgrade/upgrading-stack.asciidoc | 58 +++++++++++-------- 2 files changed, 36 insertions(+), 24 deletions(-) diff --git a/docs/en/install-upgrade/index.asciidoc b/docs/en/install-upgrade/index.asciidoc index af68eb0ca..ed577fbd9 100644 --- a/docs/en/install-upgrade/index.asciidoc +++ b/docs/en/install-upgrade/index.asciidoc @@ -5,7 +5,7 @@ :kib-repo-dir: {docdir}/../../../../kibana/docs include::{asciidoc-dir}/../../shared/attributes.asciidoc[] -include::{es-repo-dir}/Versions.asciidoc[] +include::{asciidoc-dir}/../../shared/versions.asciidoc[] include::overview.asciidoc[] diff --git a/docs/en/install-upgrade/upgrading-stack.asciidoc b/docs/en/install-upgrade/upgrading-stack.asciidoc index 5bef39511..abbb8ff93 100644 --- a/docs/en/install-upgrade/upgrading-stack.asciidoc +++ b/docs/en/install-upgrade/upgrading-stack.asciidoc @@ -223,37 +223,49 @@ indices created in {es} {prev-major-version}, but not those created in earlier versions. This restriction also applies to the internal indices that are used by Kibana and the {xpack} features. Therefore, before you can use Kibana and {xpack} features in {version}, you must upgrade the internal indices to a -compatible index structure. If you are upgrading from a version prior to -{prev-major-version}, you must upgrade to the most recent version of -{prev-major-version} first. Then you can use the {kib} Upgrade Assistant or -equivalent {ref}/migration-api-assistance.html[`_migration/assistance` API] to -check whether you need to upgrade the internal indices. - -//// -//TBD -To upgrade the `.security` index: - -. On a single node, add a temporary superuser account to the `file` realm. -. Use the {ref}/migration-api-upgrade.html[`_migration/upgrade`] -API to upgrade the security index, submitting the request with the credentials -for the temporary superuser: +compatible index structure. + +If you are upgrading from a version prior to {prev-major-version}, you must +upgrade to the most recent version of {prev-major-version} first. Then you can +use the {kib} Upgrade Assistant or the +{ref}/migration-api-assistance.html[`_migration/assistance` API] to check +whether you need to upgrade the internal indices. + +[TIP] +==== +If you use {stack} {security-features}, before you upgrade `.security*` internal +indices it is a good idea to create a temporary superuser account in the `file` +realm. + +. On a single node, add a temporary superuser account to the `file` realm. For +example, run the {ref}/users-command.html[elasticsearch-users useradd] command: + -- -[source,json] +[source,sh] ---------------------------------------------------------- -POST /_migration/upgrade/.security +bin/elasticsearch-users useradd \ +-p -r superuser ---------------------------------------------------------- -// CONSOLE -- -. Delete the temporary superuser account from the file realm. +. Use these credentials when you upgrade the `.security*` index. That is to say, +use them to log into {kib} and run the Upgrade Assistant or to call the +migration upgrade API. You can use your regular administration credentials to +upgrade the other internal indices. -You can use your regular administration credentials to upgrade the other -internal indices using the `_migration/upgrade` API. +. Delete the temporary superuser account from the file realm. For +example, run the {ref}/users-command.html[elasticsearch-users userdel] command: ++ +-- +[source,sh] +---------------------------------------------------------- +bin/elasticsearch-users userdel +---------------------------------------------------------- +-- -TIP: Once you upgrade the `.kibana` index, you can run Kibana and use the -{xpack} Reindex Helper UI to upgrade the other indices. -//// +For more information, see +{ref}/configuring-file-realm.html[Configuring a file realm]. +==== [[upgrade-elastic-stack-for-elastic-cloud]] === Upgrading on Elastic Cloud From 1fd778188da5baf0723035f2deb952b0a5ac4f2f Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 7 Mar 2019 16:19:33 -0800 Subject: [PATCH 3/5] [DOCS] Changes section level for upgrading internal indices --- docs/en/install-upgrade/upgrading-stack.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/install-upgrade/upgrading-stack.asciidoc b/docs/en/install-upgrade/upgrading-stack.asciidoc index abbb8ff93..5150936c3 100644 --- a/docs/en/install-upgrade/upgrading-stack.asciidoc +++ b/docs/en/install-upgrade/upgrading-stack.asciidoc @@ -215,7 +215,7 @@ modifications to the document data and metadata during reindexing. index as alias for the new index and delete the 2.x index. [[upgrade-internal-indices]] -==== Upgrading internal indices for {major-version} +=== Upgrading internal indices for {major-version} {es} can read indices that were created in the *previous major version*. Older indices must be reindexed or deleted. For example, {es} {major-version} can use From 19ad84f35cc564d4a3b119cdcaea5ac7ee53c8e4 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 13 Mar 2019 11:19:39 -0700 Subject: [PATCH 4/5] [DOCS] Change upgrade API to reindex API --- docs/en/install-upgrade/upgrading-stack.asciidoc | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/en/install-upgrade/upgrading-stack.asciidoc b/docs/en/install-upgrade/upgrading-stack.asciidoc index 5150936c3..714a63b3e 100644 --- a/docs/en/install-upgrade/upgrading-stack.asciidoc +++ b/docs/en/install-upgrade/upgrading-stack.asciidoc @@ -222,18 +222,17 @@ indices must be reindexed or deleted. For example, {es} {major-version} can use indices created in {es} {prev-major-version}, but not those created in earlier versions. This restriction also applies to the internal indices that are used by Kibana and the {xpack} features. Therefore, before you can use Kibana and -{xpack} features in {version}, you must upgrade the internal indices to a +{xpack} features in {version}, you must ensure the internal indices have a compatible index structure. If you are upgrading from a version prior to {prev-major-version}, you must upgrade to the most recent version of {prev-major-version} first. Then you can use the {kib} Upgrade Assistant or the -{ref}/migration-api-assistance.html[`_migration/assistance` API] to check -whether you need to upgrade the internal indices. +{ref}/docs-reindex.html[reindex API] to reindex the internal indices. [TIP] ==== -If you use {stack} {security-features}, before you upgrade `.security*` internal +If you use {stack} {security-features}, before you reindex `.security*` internal indices it is a good idea to create a temporary superuser account in the `file` realm. @@ -248,10 +247,10 @@ bin/elasticsearch-users useradd \ ---------------------------------------------------------- -- -. Use these credentials when you upgrade the `.security*` index. That is to say, +. Use these credentials when you reindex the `.security*` index. That is to say, use them to log into {kib} and run the Upgrade Assistant or to call the -migration upgrade API. You can use your regular administration credentials to -upgrade the other internal indices. +reindex API. You can use your regular administration credentials to +reindex the other internal indices. . Delete the temporary superuser account from the file realm. For example, run the {ref}/users-command.html[elasticsearch-users userdel] command: From 4d0cf9275128462eee4ff9ecd66ef5c5631d8860 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 13 Mar 2019 11:34:18 -0700 Subject: [PATCH 5/5] [DOCS] Adds additional links --- docs/en/install-upgrade/upgrading-stack.asciidoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/en/install-upgrade/upgrading-stack.asciidoc b/docs/en/install-upgrade/upgrading-stack.asciidoc index 714a63b3e..89056aa72 100644 --- a/docs/en/install-upgrade/upgrading-stack.asciidoc +++ b/docs/en/install-upgrade/upgrading-stack.asciidoc @@ -227,8 +227,9 @@ compatible index structure. If you are upgrading from a version prior to {prev-major-version}, you must upgrade to the most recent version of {prev-major-version} first. Then you can -use the {kib} Upgrade Assistant or the -{ref}/docs-reindex.html[reindex API] to reindex the internal indices. +use the {kibana-ref}/upgrade-assistant.html[{kib} Upgrade Assistant] or the +{ref}/docs-reindex.html[reindex API] to reindex the internal indices. For more +information, see {ref}/reindex-upgrade.html[Reindex before upgrading]. [TIP] ====