Documentation for LTS Upgradeability #1103

rebekah-lawrence · 2024-05-01T16:32:47Z

Initial draft, based on PRD and TDD, and the resulting Documentation Plan

netlify · 2024-05-01T16:33:06Z

✅ Deploy Preview for hardcore-allen-f5257d ready!

Name	Link
🔨 Latest commit	`1fba733`
🔍 Latest deploy log	https://app.netlify.com/sites/hardcore-allen-f5257d/deploys/667175160721d90008afa221
😎 Deploy Preview	https://deploy-preview-1103--hardcore-allen-f5257d.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

srknzl · 2024-05-02T11:55:56Z

docs/modules/maintain-cluster/pages/rolling-upgrades.adoc

+* Ensure that the <<hazelcast-members-compatibility-guarantees,Compatibility Guarantees>> cover your requirements
+* If the minimum version of JDK has changed between releases, <<updated-jdk,upgrade the JDK version>> before starting a rolling upgrade
+* If you used Hazelcast Operator to deploy your cluster, refer to the link:https://docs.hazelcast.com/operator/latest/scaling-upgrading#upgrading[Operator documentation, window=_blank]
+* If using Hazelcast Management Center to trigger your rolling upgrade, upgrade Management Center before upgrading your members. For information on upgrading Management Center, refer to the link:https://docs.hazelcast.com/management-center/5.4/getting-started/install[Management Center documentation, window=_blank]


is there a specific upgrade page we can link to instead of the getting started?

This is the Installing and Starting page, under the Getting Started section; the Upgrading page only lists the changelog, so as far as I can see, this is the only relevant page....

I've also added a link to the Operator docs for K8s users

srknzl · 2024-05-02T11:57:03Z

docs/modules/maintain-cluster/pages/rolling-upgrades.adoc

+* If you used Hazelcast Operator to deploy your cluster, refer to the link:https://docs.hazelcast.com/operator/latest/scaling-upgrading#upgrading[Operator documentation, window=_blank]
+* If using Hazelcast Management Center to trigger your rolling upgrade, upgrade Management Center before upgrading your members. For information on upgrading Management Center, refer to the link:https://docs.hazelcast.com/management-center/5.4/getting-started/install[Management Center documentation, window=_blank]
+* If using the `hz-cluster-admin` script to update your cluster, enable the `CLUSTER_WRITE` endpoints in the REST API. For further information on the REST API, see xref:maintain-cluster:rest-api.adoc#using-the-rest-endpoint-groups[REST API]
+* Plan sufficient time for the migration and upgrade to complete, and remember that members cannot join or leave during the upgrade


i wonder what you mean by join or leave during the upgrade. The restarts are also counted as joins & leaves technically

reworded to "the members cannot change during the upgrade"

srknzl · 2024-05-02T12:01:59Z

docs/modules/maintain-cluster/pages/rolling-upgrades.adoc

@@ -107,6 +134,12 @@ include::clients:partial$rest-deprecation.adoc[]

 The cluster is now operating on the new codebase version: Both the codebase version and the cluster version have been upgraded.

+=== Restart Members on Previous Version
+
+If you experience any issues during the rolling upgrade, you can recover to the previous version by restarting the members.


we are testing this 5.2-5.4 source versions to 5.5 target versio. So should we add a note about this is supported only for LTS upgrades? In the future (post 5.5) though, it'll be supported for one-minor upgrades as well as I know.

the point is, we don't test roll back in 5.2 -> 5.3 and similar upgrades

Moved to LTS-specific page; we can worry about future changes to behaviour when we get there

docs/modules/maintain-cluster/pages/rolling-upgrades.adoc

srknzl · 2024-05-02T12:08:42Z

docs/modules/maintain-cluster/pages/rolling-upgrades.adoc

+You can upgrade directly to the latest release in the following circumstances:
+
+* Your current version is no more than one minor version below the current release
+* The latest release is an xref:migrate:lts.adoc[LTS release] and your current version is among those supported


yes, and fyi the current supported version will be only the previous LTS and the previous minor in the future. For now it's 5.2-5.4 for 5.5.

Suggesting using source and target wherever possible. e.g. Your source version is no more than one minor version below the current release (target)

docs/modules/migrate/pages/lts.adoc

srknzl · 2024-05-02T12:12:10Z

docs/modules/migrate/pages/lts.adoc

+
+LTS releases have been introduced with 5.5. You can upgrade directly from 5.2 or later to 5.5 without the need to upgrade to each release between your current version and the LTS release.
+
+NOTE: Any features that are marked as Beta in your current version, or any intermediate version, are not upgraded. This is due to changes that can occur between the Beta and general availability releases. If a Beta feature has been updated or made generally available in the LTS releae, that feature is included in the LTS release. For further information on rolling upgrade compatibilities, see xref:maintain-cluster:rolling-upgrades.adoc#hazelcast-members-compatibility-guarantees[Compatibility Guarantees].


note: if you upgrade the beta question part in the rolling-upgrades page, you should also change here.

srknzl · 2024-05-02T12:14:47Z

docs/modules/migrate/pages/lts.adoc

+|Released every two years
+|Released at least twice each year
+
+|Upgrade directly from the previous LTS, or from the last available STS release


Suggested change

|Upgrade directly from the previous LTS, or from the last available STS release

|Upgrade directly from the previous LTS, or from the last available STS before the LTS release

If we don't add this, is this ambiguous? for example, last STS is 5.7 and last LTS is 5.5, then is "upgrade" (well actually downgrade :D) from 5.7 -> 5.5 possible? Probably, I am overthinking it.

I think you are overthinking, but I have reworded to be more explicit (I hope)

srknzl · 2024-05-02T12:19:49Z

docs/modules/migrate/pages/lts.adoc

+|LTS member identifies that two different minor versions are already in the cluster and rejects joining the cluster
+|===
+
+The following scenario is not supported:


we say it's not supported but we also say "Member joins the cluster" for the 5.3 member below?

It comes from the TDD: https://hazelcast.atlassian.net/wiki/spaces/PM/pages/4903993364/TDD+LTS+Upgradability#Mixed-version-clusters

It is a difficult once to cover in a positive way, I have amended, but any suggestions are more than welcome!

frant-hartm · 2024-05-22T07:12:44Z

docs/modules/maintain-cluster/pages/rolling-upgrades.adoc

+
+As newer JDK releases contain improvements, we recommend that you upgrade to a newer JDK version where xref:deploy:versioning-compatibility.adoc#supported-java-virtual-machines[supported].
+
+Upgrade the JDK version before upgrading your members if support for the JDK version has changed between your current and planned cluster versions. For example, in 5.2 JDK 8 was supported, but 5.5 supports only JDK 17 or later. 


Suggested change

Upgrade the JDK version before upgrading your members if support for the JDK version has changed between your current and planned cluster versions. For example, in 5.2 JDK 8 was supported, but 5.5 supports only JDK 17 or later.

Upgrade the JDK version before upgrading your members if support for the JDK version has changed between your current and planned cluster versions. For example, in 5.2 JDK 8 or later was supported, but 5.5 supports only JDK 17 or later.

To make it cleare that there is an overlap of supported JDK versions.

frant-hartm · 2024-05-22T07:15:17Z

docs/modules/migrate/pages/lts.adoc

+
+{description}
+
+LTS releases have been introduced with 5.5. You can upgrade directly from 5.2 or later to 5.5 without the need to upgrade to each release between your current version and the LTS release.


Should we specify that they should upgrade from the latest patch of each release line? We only test latest patch (at the time of the release).

frant-hartm · 2024-05-22T07:20:10Z

docs/modules/migrate/pages/lts.adoc

+
+=== Restart Members on Previous Version
+
+If you experience any issues during the rolling upgrade, you can recover to the previous version by restarting the members.


This can be done only if the version hasn't been upgraded (either automaticaly or via API/script).

frant-hartm · 2024-05-22T07:28:41Z

docs/modules/migrate/pages/lts.adoc

+
+a|* IMap data structure. This includes the API, configuration options, and persistence
+* CP subsystem. This inclues the API and peristence
+* WAN replication. Ongoing replication is supported during the upgrade. This includes both source and target; however, the source and the target cannot be upgraded simultaneously


We tested replication to clusters 5.2+ during the RU, not to earlier clusters. So we should specify we support only that.

Including Avtar's responses in the Slack thread

oliverhowell

Coupla minor typos and a few minor suggestions and comments but pre-approving

oliverhowell · 2024-06-12T11:35:22Z

docs/modules/maintain-cluster/pages/rolling-upgrades.adoc

@@ -5,6 +5,18 @@

 {description}

+== Best Practices
+
+Before starting a rolling upgrade, consider the following best practises:


Suggested change

Before starting a rolling upgrade, consider the following best practises:

Before starting a rolling upgrade, consider the following best practices:

Dagnamit! When will those US English practitioners learn how to use words properly ;-)

oliverhowell · 2024-06-12T11:36:49Z

docs/modules/maintain-cluster/pages/rolling-upgrades.adoc

+
+* Ensure that the <<hazelcast-members-compatibility-guarantees,Compatibility Guarantees>> cover your requirements
+* If the minimum version of JDK has changed between releases, <<updated-jdk,upgrade the JDK version>> before starting a rolling upgrade
+* If you used Hazelcast Operator to deploy your cluster, refer to the link:https://docs.hazelcast.com/operator/latest/scaling-upgrading#upgrading[Operator documentation, window=_blank]


Trying to avoid a big naming thread but should 1st ref be Hazelcast Platform Operator? I might be out of date on this...

The (last) rename that I saw dropped Platform to make it just Hazelcast Operator - and this also matches the [current] naming in the side nav of the docs.

Actually, I think the last one I saw was Hazelcast Enterprise Operator, but Platform was definitely not part of the name.

I suggest leaving as is - if it needs to be changed, we can do that anytime.

oliverhowell · 2024-06-12T11:38:03Z

docs/modules/maintain-cluster/pages/rolling-upgrades.adoc

+* If the minimum version of JDK has changed between releases, <<updated-jdk,upgrade the JDK version>> before starting a rolling upgrade
+* If you used Hazelcast Operator to deploy your cluster, refer to the link:https://docs.hazelcast.com/operator/latest/scaling-upgrading#upgrading[Operator documentation, window=_blank]
+* If using Hazelcast Management Center to trigger your rolling upgrade, upgrade Management Center before upgrading your members. For information on upgrading Management Center, refer to the link:https://docs.hazelcast.com/management-center/5.4/getting-started/install[Management Center documentation, window=_blank], or if you deployed Management Center using the Hazelcast Operator, refer to the link:https://docs.hazelcast.com/operator/latest/deploy-management-center.adoc[Operator documentation, window=_blank]
+* If using the `hz-cluster-admin` script to update your cluster, enable the `CLUSTER_WRITE` endpoints in the REST API. For further information on the REST API, see xref:maintain-cluster:rest-api.adoc#using-the-rest-endpoint-groups[REST API]


Which REST API page should this be? The new enterprise-rest-api or the old legacy one (you've linked here)

@frant-hartm @srknzl can you guide me on this one? Ta!

The new REST API supports changing the version, so it should be the new one. However, I don't see the change version endpoint in the docs yet.

I've added a link to the Enterprise REST API topic, and added Community to the existing link; if the new REST API adds a better place to link to, we can adjust it later.

Hey @rebekah-lawrence I'm informed that old REST api is deprecated in the upcoming 5.5 release, so we should start referring to the new documentaiton instead.

There's a swagger API documentation page with all endpoints. The new REST API's reference manual may be a bit missing right now @frant-hartm

@srknzl yes, I added a link to the new REST API as well as the existing in the final updates. The swagger docs are going to be embedded in the docs, I believe. If the link needs to be updated before 5.5 goes live I will take care of it.

Thanks for mentioning it, though, just to keep it fresh in my mind - I've added a note to the docs Jira to double-check the link destinations once the REST API doc updates are merged.

oliverhowell · 2024-06-12T11:43:16Z

docs/modules/maintain-cluster/pages/rolling-upgrades.adoc

@@ -48,8 +60,23 @@ As a result, you can use rolling upgrades to upgrade clusters to the following m
 +
 This also includes the ability of rolling upgrade from Hazelcast IMDG 4.2 to Platform 5.0, since IMDG is part of the Platform and 5.0 is considered to be the next minor version after IMDG 4.2.

+- Releases from 5.2 to 5.4, directly to the 5.5 Long-term Support (LTS) release. For further information on additional compatibilities for direct-to-LTS rolling upgrades, see xref:migrate:lts.adoc[].


Suggested change

- Releases from 5.2 to 5.4, directly to the 5.5 Long-term Support (LTS) release. For further information on additional compatibilities for direct-to-LTS rolling upgrades, see xref:migrate:lts.adoc[].

- Directly to the 5.5 Long-term Support (LTS) release from releases 5.2 through 5.4. For further information on additional compatibilities for direct-to-LTS rolling upgrades, see xref:migrate:lts.adoc[].

Reads a little awkwardly with the source releases at front, just a suggestion...

Changed to: The 5.5 Long-term Support (LTS) release direct from 5.2.x to 5.4.x.

Which is actually better for list parallelism as well as readability! Good catch.

oliverhowell · 2024-06-12T11:48:45Z

docs/modules/migrate/pages/lts.adoc

+
+{description}
+
+LTS releases have been introduced with 5.5. You can upgrade directly from 5.2.x or later to 5.5 without the need to upgrade to each release between your current version and the LTS release. We recommend that you upgrade to 5.5 from the latest available patch for your current release.


I know the context is already Platform but with the various product/version combinations in this section, is it worth being explicit with?

Suggested change

LTS releases have been introduced with 5.5. You can upgrade directly from 5.2.x or later to 5.5 without the need to upgrade to each release between your current version and the LTS release. We recommend that you upgrade to 5.5 from the latest available patch for your current release.

LTS releases have been introduced with Hazelcast Platform 5.5. You can upgrade directly from 5.2.x or later to 5.5 without the need to upgrade to each release between your current version and the LTS release. We recommend that you upgrade to 5.5 from the latest available patch for your current release.

oliverhowell · 2024-06-12T11:51:04Z

docs/modules/migrate/pages/lts.adoc

+|Choose if you value new features over stability, you are willing to upgrade several times a year, and you are happy with maintenance support for the life of the STS
+|===
+
+== Hazelcast 5.5 LTS


Is it just Hazelcast 5.5 in this context?

This time, yes, as it is being introduced in 5.5 - however, my thought process was that in the future people might upgrade first to the 5.5 LTS, then to the [6.5] LTS, so sections would be required going forward for each usable LTS release........

docs/modules/migrate/pages/lts.adoc

oliverhowell · 2024-06-12T11:52:53Z

docs/modules/migrate/pages/lts.adoc

+* CP subsystem. This inclues the API and peristence
+* WAN replication. Ongoing replication is supported during the upgrade. This includes both source and target; however, the source and the target cannot be upgraded simultaneously
+
+NOTE: Replication has been tested for 5.2 or later clusters only.


But context for this line is only versions 5.2 and 5.3 anyway - does this add anything?

Added from a comment from @frant-hartm - but a fair point.

What do you think, @frant-hartm, or did I miss the point of your original comment?

When there is WAN replication you have 2 clusters and 3 different versions.

from version of cluster A (any of 5.2, 5.3, 5.4),
to version of cluster A

version of cluster B - this could be any Hazelcast version 4.0-5.4.

We tested only 5.2, 5.3 and 5.4 for cluster B.

Expanded to "NOTE: Hazelcast has tested WAN Replication to validate the upgrade solution. The test covered two clusters of different versions; for scenarios where WAN Replication is used from a cluster with a version or 5.2, 5.3, or 5.4 to another cluster with a version between 4.0 and 5.4, only the replication to clusters of version 5.2 or later have been tested."

docs/modules/migrate/pages/lts.adoc

oliverhowell · 2024-06-12T11:55:47Z

docs/modules/migrate/pages/lts.adoc

+
+=== Restart Members on Previous Version
+
+If an automatic upgrade, an upgrade using the API, or using a script has not successfully upgraded the version, you can recover to the previous version by restarting the members.


Suggested change

If an automatic upgrade, an upgrade using the API, or using a script has not successfully upgraded the version, you can recover to the previous version by restarting the members.

If an automatic upgrade, or an upgrade using the API or script, has not successfully upgraded the version, you can recover to the previous version by restarting the members.

Yes, I wrote and rewrote this sentence! Your version is how I had it originally, but I felt the commas spoiled the flow.

I'm going to rejig this as follows:

If the version has not successfully upgraded following an upgrade, you can recover to the previous version by restarting the members. This is the case whether the upgrade was done automatically, using the API, or using a script.

srknzl · 2024-06-12T13:04:04Z

docs/modules/migrate/pages/lts.adoc

+|Released every two years
+|Released at least twice each year
+
+|Upgrade directly from the previous LTS, or from the STS release that precedes the latest LTS release


Upgrade directly from the previous LTS, or from the STS release that precedes the latest LTS release

@frant-hartm should this be "Upgrade directly from the previous LTS" only? I think for 5.5 we are making an exception and make it work for "Upgrade directly from the previous LTS, or from the STS release that precedes the latest LTS release"

But surely there is no previous STS or LTS for 5.5 - and we have covered this in the remaining text?

This table covers the logic/behaviour for LTS/STS releases as they will be - it was difficult to convey the idea without getting bogged down in the initial implementation where there are no other LTS or STS releases avaialbe.

We could be specific for this release and say something like:

For the initial LTS release with 5.5, you can upgrade directly from 5.2.x or later.

In future LTS releases, you can

Of course, this then raises the question of whether we need to add something like (when available) or (available from release ????) in the STS header.

Then this additional wording can be stripped as we progress through the availability of STS releases and further LTS releases.

srknzl

lgtm from my perspective

Documentation for LTS Upgradeability

b237e87

Initial draft, based on PRD and TDD, and the resulting Documentation Plan

rebekah-lawrence requested review from frant-hartm, srknzl and AleksPeychev May 1, 2024 16:32

rebekah-lawrence requested review from Serdaro and oliverhowell as code owners May 1, 2024 16:32

srknzl reviewed May 2, 2024

View reviewed changes

Updated from review comments

51cda42

rebekah-lawrence requested a review from srknzl May 9, 2024 16:02

frant-hartm suggested changes May 22, 2024

View reviewed changes

frant-hartm reviewed May 22, 2024

View reviewed changes

rebekah-lawrence mentioned this pull request Jun 12, 2024

Document multiple level rolling upgrade [MC-2820]. hazelcast/management-center-docs#328

Merged

Updated from Franta's comments

0c5f4d0

Including Avtar's responses in the Slack thread

rebekah-lawrence requested a review from frant-hartm June 12, 2024 11:15

oliverhowell approved these changes Jun 12, 2024

View reviewed changes

srknzl reviewed Jun 12, 2024

View reviewed changes

srknzl approved these changes Jun 12, 2024

View reviewed changes

rebekah-lawrence added 2 commits June 12, 2024 16:45

Updated from Olly's review

1a3d500

Updated from Frantisek's responses

1fba733

frant-hartm approved these changes Jun 20, 2024

View reviewed changes

rebekah-lawrence merged commit 69fe7c3 into main Jun 20, 2024
6 checks passed

rebekah-lawrence deleted the DOCS-880-Document-LTS-Upgradeability branch June 20, 2024 08:51


		LTS releases have been introduced with 5.5. You can upgrade directly from 5.2 or later to 5.5 without the need to upgrade to each release between your current version and the LTS release.

		NOTE: Any features that are marked as Beta in your current version, or any intermediate version, are not upgraded. This is due to changes that can occur between the Beta and general availability releases. If a Beta feature has been updated or made generally available in the LTS releae, that feature is included in the LTS release. For further information on rolling upgrade compatibilities, see xref:maintain-cluster:rolling-upgrades.adoc#hazelcast-members-compatibility-guarantees[Compatibility Guarantees].

	\|Upgrade directly from the previous LTS, or from the last available STS release
	\|Upgrade directly from the previous LTS, or from the last available STS before the LTS release


		As newer JDK releases contain improvements, we recommend that you upgrade to a newer JDK version where xref:deploy:versioning-compatibility.adoc#supported-java-virtual-machines[supported].

		Upgrade the JDK version before upgrading your members if support for the JDK version has changed between your current and planned cluster versions. For example, in 5.2 JDK 8 was supported, but 5.5 supports only JDK 17 or later.


		{description}

		LTS releases have been introduced with 5.5. You can upgrade directly from 5.2 or later to 5.5 without the need to upgrade to each release between your current version and the LTS release.


		=== Restart Members on Previous Version

		If you experience any issues during the rolling upgrade, you can recover to the previous version by restarting the members.

	Before starting a rolling upgrade, consider the following best practises:
	Before starting a rolling upgrade, consider the following best practices:

	- Releases from 5.2 to 5.4, directly to the 5.5 Long-term Support (LTS) release. For further information on additional compatibilities for direct-to-LTS rolling upgrades, see xref:migrate:lts.adoc[].
	- Directly to the 5.5 Long-term Support (LTS) release from releases 5.2 through 5.4. For further information on additional compatibilities for direct-to-LTS rolling upgrades, see xref:migrate:lts.adoc[].

	LTS releases have been introduced with 5.5. You can upgrade directly from 5.2.x or later to 5.5 without the need to upgrade to each release between your current version and the LTS release. We recommend that you upgrade to 5.5 from the latest available patch for your current release.
	LTS releases have been introduced with Hazelcast Platform 5.5. You can upgrade directly from 5.2.x or later to 5.5 without the need to upgrade to each release between your current version and the LTS release. We recommend that you upgrade to 5.5 from the latest available patch for your current release.


		=== Restart Members on Previous Version

		If an automatic upgrade, an upgrade using the API, or using a script has not successfully upgraded the version, you can recover to the previous version by restarting the members.

	If an automatic upgrade, an upgrade using the API, or using a script has not successfully upgraded the version, you can recover to the previous version by restarting the members.
	If an automatic upgrade, or an upgrade using the API or script, has not successfully upgraded the version, you can recover to the previous version by restarting the members.

Documentation for LTS Upgradeability #1103

Documentation for LTS Upgradeability #1103

Conversation

rebekah-lawrence commented May 1, 2024

netlify bot commented May 1, 2024 • edited Loading

✅ Deploy Preview for hardcore-allen-f5257d ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

srknzl May 2, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

srknzl May 2, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

oliverhowell left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

srknzl left a comment • edited Loading

Choose a reason for hiding this comment

netlify bot commented May 1, 2024 •

edited

Loading

srknzl May 2, 2024 •

edited

Loading

srknzl May 2, 2024 •

edited

Loading

srknzl left a comment •

edited

Loading