7.0 upgrade docs need to be updated

[cjcenizal]

The 7.0 upgrade docs prescribe a standard upgrade when upgrading from 6.x to 7.x.

Clarify versions

The user should upgrade to 6.7 before going to 7.x, correct? In that case, we may want to update the table to have specific version you need to be on, and provide more guidance around that process, e.g. "If you're on a 6.x version, you need to upgrade to 6.7 before upgrading to 7.x."

Current

Proposal

Mention reindexing?

Do we need to make any mention of reindexing or is that all done automatically now? If automatic, is it worth making a note of that to reassure the user / provide transparency?

Mention use of Upgrade Assistant

The standard upgrade docs don't mention the UA. We should provide guidance around how to use the UA, with links to related docs and/or screenshots.

[elasticmachine]

Pinging @elastic/kibana-docs

[elasticmachine]

Pinging @elastic/kibana-operations

[joshdover]

I agree this isn't as clear as it could be. While Elasticsearch and Kibana do support rolling upgrades from any 6.x version to 7.x version, 7.x ES nodes will fail to start if any indices in the cluster were created in 5.x (not reindexed with the Upgrade Assistant). However, for customers who started using Elasticsearch in 6.x, going through 6.7 is not required, but still recommended especially for customers using Beats.

I like this change, but I think we should also make sure our guidance is consistent across the Stack. This time around we shouldn't need a the Interactive Upgrade Guide but we should have a clear table explaining what to do at the Stack level as things have become more interconnected. Does it make sense to have any guidance here? I tend to think that linking to one Stack-level source of truth document would make sense for Kibana docs and all other product docs.

[cjcenizal]

However, for customers who started using Elasticsearch in 6.x, going through 6.7 is not required, but still recommended especially for customers using Beats.

Does it make sense to have any guidance here? I tend to think that linking to one Stack-level source of truth document would make sense for Kibana docs and all other product docs.

I think having a single Stack-level source-of-truth makes sense. We can describe various scenarios and steps that need to be taken in the Stack docs, including the one you mentioned about Beats. It might make sense to link back to them from each product's upgrade page, for example in the context of a caveat: "Note: if you're upgrading your entire stack, please consult the Stack Upgrade docs for other steps you might need to take in addition to those described here."

@joshdover What do you think about my mention of the 7.0 Upgrade Assistant? Is that something users should be made aware of on this page?

[cjcenizal]

However, for customers who started using Elasticsearch in 6.x, going through 6.7 is not required

It looks like node-sniffing wasn't introduced until 6.6. In that case, anyone who is trying to use Kibana's Console to run the ES rolling upgrade commands will get blocked once the node serving Kibana is taken offline.

Again, something that's probably more appropriate for the Stack upgrade docs.

[jbudz]

The rolling upgrade commands are run before a node is taken offline and after it comes back up, so I would expect it to be okay. There's probably an edge case tho, so it won't hurt.

[cjcenizal]

@jbudz You're right, in most cases the user can just wait for Kibana to become available again. Though it does seem worth letting the user know what they can expect so that they don't interpret it as something gone wrong in the upgrade process.

[schersh]

I talked this through with @lcawl , and for the 7.0 branch, we agreed that it doesn't make sense to include upgrade information dating back to 3.0. That information exists in the appropriate historical branches, so 7.0 should focus on the upgrade from 6.x to 7.0, and should link to the Stack Upgrade Guide as the single source of truth and highlight the Upgrade Assistant. I'm going to take a pass at updating this and then I'll ask for feedback.

[schersh]

I have a PR open to make updates to the Upgrading Kibana docs: #34121 Feedback is very welcome! I'm out of the office most of today, but please feel free to make comments and I can catch up on Monday. I tried to make the docs more current to the 7.0 upgrade, since the material for earlier upgrades is available in earlier branches.

[schersh]

Fixed by #34121