Adds ECE upgrade guide

[kosabogi]

This PR adds the "Upgrade Elastic Cloud Enterprise" page and the "Re-running the ECE upgrade" page as a child page.

We still have a few outstanding questions that need to be addressed, as outlined in this Google document:

• We need to verify the accuracy of the Version matrix table.
• Based on this comment, I have added a new section titled "Preserve installation flags during upgrade," including guidance from the linked Slack thread. Could you confirm if this is the correct approach and if it is technically accurate?
• Should we keep this note:
  "If you are upgrading to ECE versions 2.10, 2.11, or 2.12, refer to the ECE version 2.12 upgrade steps for guidance about certain default ECE visualizations not working."
• We need clarification on this question.
  @yang-wei, could you please provide guidance?
• Regarding this statement:
  "Note that the only exception to that rule is when you’re upgrading to ECE 3.6.0 and your system deployments are at a version lower than 7.17.0.",
  we should clarify this and this question.

Rel: https://elasticco.atlassian.net/browse/CP-10312

[jmikell821]

Hi @kunisen @jakommo — would you mind reviewing this PR please? We have a few questions posted here as well, if you're able to provide feedback. Thanks in advance for your help and please let me know if there are any other Cloud folks we should loop in.

[kunisen]

Thanks @jmikell821 for the ping.

I had a chat with @jakommo and we believe that it should be the control plane team to lead this doc creation effort from technical perspective (instead of us - support team) and make a base officially, and we are more than happy to also review and provide our thoughts based on the base.

That said, sorry for the back and forth, but may I trouble you to check with Control Plane Hosted Foundations team and Control Plane Hosted Application team first please? 🙏

Hope that makes sense and please let me know if this is not clear.

[eedugon]

@jmikell821 , @kosabogi ,

IMO, the objective at this moment should be not to have a valid document for 4.0.0 upgrade, but to migrate and put into the new IA and docs V3 the ECE upgrade documentation (with the data of upgrading to latest 3.16, not to 4.0.0), and from there we can handover the doc to cloud team to update the upgrade documentation and be valid for 4.0.0 in a different PR, as that will be part of their 4.0.0 release process.

Also, I don't think support engineers can help with the technical validation of the 4.0.0 upgrade specifics as for example we cannot know if 2.13 can be upgraded directly to 4.0.0 (I strongly doubt it by the way) or not, only devs will know.

I wouldn't even change in the original doc the occurrences of 3.16 for 4.0.0, as that can create future issues, better if the owners of the upgrade process (devs / PMs) take care of the content or provide instructions for it.

What do you think? cc: @shainaraskas I think we are mixing here migration effort with the new releases process.

Update after reviewing the shared gdoc: I see devs have shared comments in the doc about the upgrade path to 4.0. I've reviewed the PR accordingly.

[eedugon]

Shared a few suggestions and comments in case this hasn't been validated by devs yet.
I think we should assume (except if we are told otherwise), that:

• Upgrading directly to 4.0/4.x will only be supported from ECE 3.7 (and probably 3.7.latest). Update: devs confirmed that it should be 3.8 (i have updated my review to that fact)

The current doc was assuming ECE upgrade from 2.13 to 4.x can be achieved with a unique step.

Anyway as I said in the discussion this should be validated by devs, either now or after merging, as part of their ECE 4.0.0 release process.

[przemek-grzedzielski]

Hey I'm leading the development side of the ECE 3.8 effort and just learned about this PR (thanks a lot for this, btw!). I can see this refers to ECE 4.0. Is there a documentation update effort going on for ECE 3.8? We will most likely need to make several updates to ECE upgrade docs for ECE 3.8 first and I'm wondering if we should be opening a PR against master and backporting it to ms-119 (base branch for ECE 3.8) or opening a PR against ms-119 directly. What do you think @elastic/platform-docs ?

[florent-leborgne]

@przemek-grzedzielski 3.8 docs are still in the cloud repo (branch ms-119). We can update those over there on that branch directly, and I'll be happy to assist. Also the 3.8 release notes are here if we need to edit them with the most recent work that was carried out https://github.com/elastic/cloud/pull/136956

[przemek-grzedzielski]

Awesome, thank you and sorry for the noise on this one!

[eedugon]

@przemek-grzedzielski , FYI this PR includes the original ECE 3.7 upgrade doc migrated from asciidoc to markdown, with
minor changes like aiming to ECE 4.0 and drafting the new upgrade paths (which of course will need to be updated at a later stage).

@florent-leborgne , @przemek-grzedzielski , if possible, please keep me in the loop of the ECE 3.8 upgrade documentation effort, as I'd like to provide feedback on the final doc. It would be great to improve some parts that were a bit ambiguous in the past and refer to https://www.elastic.co/guide/en/cloud-enterprise/current/ece-system-deployment-versions.html in the relevant parts of the new upgrade doc.

After ECE 3.8 doc is published we will be able to refine and update this doc (ECE 4.0 upgrade) further.

@jmikell821 , @kosabogi , @florent-leborgne : Should we merge this PR anyway to have at least a draft of ECE 4.0 document or should we cancel this PR and create a new one starting with the ECE 3.8.0 document whenever is ready? My suggestion would be to merge this and refine it at a later stage with the needed changes, but maybe you prefer to keep https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/upgrade/orchestrator/upgrade-cloud-enterprise empty until we have the final doc.

[florent-leborgne]

Merge and refine later sounds best to me

[eedugon]

LGTM!
It would need some small refinements, but maybe better in a later PR when the technical content is updated after we generate the 3.8 upgrade document.

[kunisen]

Thanks all for the great effort on this! Much appreciated! 🙏

I had a sync with @jakommo and we think something might be worth calling out:

:: [1] To ECE dev team (@przemek-grzedzielski)

We think it might be good to remove some descriptions of the old versions.

Example: make sure Elastic Cloud Enterprise is upgraded to at least version 2.5.0, this is probably no longer needed if user is on 3.x already.

I reread the preview doc link and found many of the old descriptions are already cleaned up which is awesome and thanks. However, it seems like we may still have some left over.

=> That said, @przemek-grzedzielski may I have your opinion on that, could you please kindly help review those old descriptions and see if we are good to cut them in the ECE 4 upgrading doc?

:: [2] Work on support side

We think it's good to add examples of ECE 4.0 upgrading path, e.g.

• [OS + Docker] Upgrade path:
  • Sample 1 - ECE 3.6 on Ubuntu 20 with Docker v20.
  • Sample 2 - ECE 3.6 on SLES 12 with Docker v18.
• [OS + Podman] Upgrade path:
  • Sample 3 - ECE 3.6 on CentOS 7 with Docker v20.
  • Sample 4 - ECE 3.6 on RHEL 9 with Podman 4 (to Podman 5)

We discussed this in some internal tickets (Jira CP-10312, Jira CP-10505).
Kuni will prepare this part for better upgrading readiness and visibility.

---

IMHO, the above [1] and [2] are related to this ECE upgrade guide but could be handled separately.

That said, may I trouble you to share your thoughts on the above, if anything is not clear or missing please?
Also, if we are on the same page, then I am happy to file another doc PR later for [2].

Thanks again!

[przemek-grzedzielski]

=> That said, @przemek-grzedzielski may I have your opinion on that, could you please kindly help review those old descriptions and see if we are good to cut them in the ECE 4 upgrading doc?

Of course I'm happy to review (and planning on doing this). However, it seems to me that it was agreed that this PR is a tentative version and will undergo some more work. Ideally I'd like my team to do a technical review once the doc's structure is more or less ready vs doing multiple reviews now and then many more times in the future. It's just easier and more efficient from our perspective and at the moment we really need to make sure that our efforts are concentrated on the right things for ECE 3.8.

So if this is the final version of the document from the @\elastic/platform-docs perspective, please let me know and we'll review the technical aspects 👍 If you're about to make more amendments, please let us know once they're in place :-) Thank you! 🙇

[florent-leborgne]

@przemek-grzedzielski @kunisen I suggest we first focus on the ECE 3.8 upgrade doc, then review this one only after, since if I understand correctly, anyone upgrading to 4.0 will need to upgrade to 3.8 first, so we will have a better view of what we can keep and what we can dismiss in this one.

Unless there are obvious changes we can already make :)