Clarify limitations of the migration assistant

[elasticmachine]

Original comment by @ppf2:

As much as we want customers to read the guides, review all breaking changes, test in qa/dev (ha!), these don't always happen in practice. We have customers who pretty much think that they can just run the migration plugin and if it doesn't find issues, they can just upgrade. In previous versions, we do have a somewhat misleading statement in our docs that is a bit too general:

The elasticsearch-migration plugin (compatible with Elasticsearch 2.3.0 and above) will help you to find issues that need to be addressed when upgrading to Elasticsearch 5.0.

So it will be helpful if we can put a disclaimer in the migration assistant UI to set expectations that the migration assistance will not catch everything. Specifically, the type of issues it will not be able to catch are configuration/setup issues that will cause the node to fail to start up entirely (fail so soon such that the assistance or upgrade apis will not even run because the endpoints are not available). A few examples from the past include:

• Network changes where network.host binds to localhost by default (1.x -> 2.0)
• Changes in how one defines Elasticsearch settings (eg. -Des -> -E, etc..) (2.x -> 5.0)

A really thorough way to tackle this is to label every breaking change that cannot be caught by the migration assistant as such in our documentation. But this can add a lot of overhead, so maybe we can start with just setting expectations directly in the migration tooling?

[elasticmachine]

Original comment by @Rasroh:

@archanid - is this something you can look at for the migration assistant ?

[elasticmachine]

Original comment by @archanid:

I can take this on. Thanks for the heads up.

[tylersmalley]

@dover @gchaps - Do you think our wording covers the concern here?

[joshdover]

@tylersmalley We don't currently have any wording in the UI that hints at the upgrade assistant not being comprehensive.

That said, I think the types of issues that would prevent an ES node from starting should be self evident from the ES logs themselves. When I discussed these types of issues with Gordon, the only known issue we were able to identify is the Security realms settings structure which an only be fixed on 7.0 AND is flagged by the Migration Assistance API in 6.7.

The only other types of issue I can think of would be using outdated ES plugins, but the logs on startup should make this pretty clear as well.

However, if we want to make this heading text a bit less authoritative (?), that may be a good idea:

This assistant checks your cluster and indices and identifies the changes you need to make before upgrading to Elasticsearch 7.x.

@gchaps, what do you think?

[gchaps]

@tylersmalley @joshdover

How about this:

This assistant helps you prepare your cluster and indices for Elasticsearch 7.x. For other issues that need your attention, see the Elasticsearch logs.

[joshdover]

Sounds great. I'm going to tack that on to this PR: #30432