[DOCS] Clarifies how to upgrade internal indices #235
Conversation
|
In case it helps, you can preview the pertinent page here: https://doc-review-63bf6.firebaseapp.com/x/upgrading-elastic-stack.html#upgrade-internal-indices |
| 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 |
There was a problem hiding this comment.
I believe that Kibana reindexes it's own index these days. @epixa can you confirm?
There was a problem hiding this comment.
We do, but if someone was attempting to upgrade from something like 6.2 to 7.x, then they wouldn't have run saved object migrations yet, so their index could have originated back in 5.6. So they'll still need to run something like 6.7 first to ensure the index is migrated.
We also don't delete the old indices automatically, we just create new ones for migrations. Does ES fail to start if it has old indices or does it just not recognize those indices?
Finally, this blurb of text would still mostly make sense even with Kibana doing migrations of its own index. We indirectly rely on ES things like the security index, so if that needs to be functional in order for Kibana (with security) to be accessible.
There was a problem hiding this comment.
Thanks @epixa .
We also don't delete the old indices automatically, we just create new ones for migrations. Does ES fail to start if it has old indices or does it just not recognize those indices?
Yes. ES will refuse to start.
but if someone was attempting to upgrade from something like 6.2 to 7.x, then they wouldn't have run saved object migrations yet, so their index could have originated back in 5.6
This implies that they'll do a full cluster restart, which will also mean that their ES 7.0 will indeed fail to start and they will be forced to downgrade and fix it.
@lcawl part of the confusion is caused by the usage of the word "upgrade" - in 5.x we had a dedicated upgrade API that people needed to activate. With 6.x it's a vanilla reindex via the reindex API (or the migration assistant UI). I think we should change the doc a bit to reflect this.
There was a problem hiding this comment.
@bleskes Do you mean that in these steps we should be advising users to call the reindex API (https://www.elastic.co/guide/en/elasticsearch/reference/7.0/docs-reindex.html) instead of the migration upgrade API
(https://www.elastic.co/guide/en/elasticsearch/reference/7.0/migration-api-upgrade.html)?
There was a problem hiding this comment.
Do you mean that in these steps we should be advising users to call the reindex API instead of the migration upgrade API
We should tell people that the index needs to be reindexed. That can be done via the migration assistant UI or alternatively directly via the reindex API (In that order ;))
There was a problem hiding this comment.
Thanks @bleskes ! I've updated the text to reflect that. Should we also update the documentation for the migration upgrade API (https://www.elastic.co/guide/en/elasticsearch/reference/master/migration-api-upgrade.html) to recommend that they use the reindex API instead?
There was a problem hiding this comment.
Thx @lcawl . Re the upgrade api - I had a quick chat with @gwbrown about what to do with them, I think he was taking it up to the team to decide. @gwbrown , do I recall correctly?
There was a problem hiding this comment.
Yes, we should also update the docs for the Migration Upgrade API to point users towards the Kibana Upgrade Assistant - we're also going to be deprecating the Migration Assistance and Migration Upgrade APIs in 6.7 and removing in 7.0, see elastic/elasticsearch#40014. I'll have PRs up for that later today.
There was a problem hiding this comment.
Thanks! I also implemented those changes in #247
|
This PR will be replaced by elastic/elasticsearch#40019 since this section is disappearing from the Installation and Upgrade Guide in #242 |
Related to #226
Dependent on elastic/docs#675
This PR clarifies the following section of the Installation and Upgrade Guide:
https://www.elastic.co/guide/en/elastic-stack/master/upgrading-elastic-stack.html#upgrade-internal-indices