Deprecate the Migration APIs #40014
Description
The Migration APIs (Migration Assistance and Migration Upgrade) were used in the transition from version 5.x of the stack to version 6.x, but are not being used for the 6.x to 7.x transition, and may or may not be used for the 7.x to 8.x transition.
What should we do with these APIs in the meantime?
The Migration Upgrade API in particular was used to prepare a 5.x cluster for the upgrade to 6.x, and can be used in 6.x to fix the problems that occur if it was not used prior to the upgrade. However, to prepare a 6.x cluster for the upgrade to 7.x, users should use the Kibana Upgrade Assistant, or reindex their indices by hand - the internal indices that the Migration Upgrade API is used to manage don't need special handling for this upgrade (with the exception that the new security index needs to be named .security-7 I believe), and can be reindexed without any special consideration.
The Migration Assistance API shows which indices need to be reindexed, a task which has been taken over (and expanded upon) by the Deprecation Info API
In testing and preparing documentation for the 6 to 7 upgrade, we've seen some confusion even with Elastic about the Migration APIs, and I expect users to be even more confused. We should take some steps to help users avoid this confusion. While it's a bit late to make code changes to 6.7 or 7.0, we should at least update the documentation to point users to the correct upgrade path for 6 to 7, and consider where we want these APIs to go in the future.
My opinion is that:
- the Migration Assistance API should be deprecated and eventually removed,
- the Migration Upgrade API documentation should be updated to clearly point users to Kibana Upgrade Assistant for preparing a 6.x cluster for and upgrade, and
- we should determine what we want to do with the Migration Upgrade API in the 7.x series, as it may be useful to keep long-term if more involved changes to internal indices are needed for 8.x, but confusing for users in the short term.