Revise rolling upgrade guide

[hammerhead]

About

We received feedback that the rolling upgrade guide was hard to follow for new users who aren't familiar yet with distributed systems. While the overall upgrade process was documented well before, there were the following issues:

• Step-by-step instructions were interrupted by lengthy educational background information on certain parameters and their implications, causing a loss of focus. Now: Focus on the flow with default settings, elaborate on possible deviations separately.
• Added an initial health check to ensure the cluster is green before starting
• Removed a warning that upgrades aren't possible from "testing versions". This is not applicable if we understand "testing versions" as the testing channel, which are regular releases. It may have targeted nightly builds, but those aren't supported anyway.
• Some of the SQL statements were outdated, querying _node instead of node from sys.shards, and also unnecessarily limiting their result to the schemas doc and blob.
• There was an incorrect statement about writes only succeeding if a quorum of shards are present, contradicting the documentation of write.wait-for-active-shards
• Replaced the outdated system command with modern systemctl in examples
• The "Repeat" step was inconsistent, asking to issue SET GLOBAL TRANSIENT "cluster.routing.allocation.enable" = 'new_primaries'; after upgrading every single node, even though it wasn't reset
• Added a post-upgrade health check to see if everything is back to green
• Provided clearer guidance when to use min_availability options full, none, or primaries

Pending clarifications

• Unsafe cluster.routing.allocation.enable recommendation for zero downtime upgrades crate#19751

Preview

https://cratedb-guide--599.org.readthedocs.build/admin/upgrade/rolling.html

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c25f1703-918a-446b-ba1f-4aad3a5f3f49

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch hammerhead/upgrade

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[karynzv]

The warning mentioned below has been removed. Should we keep it? Also, maybe add a comment for nightly versions as well, something like "There's no guarantee that updating from nightly to another version, be that a new nightly or a testing/stable version works."

Rolling upgrades are only possible if you are using a stable version of CrateDB. If you are upgrading to a testing version you must perform a full cluster restart.

[hammerhead]

As mentioned in the PR's description, the term "testing versions" is unclear and the statement about rolling upgrades not working appears too general. If there is a release with particularities around upgrading, it would usually be mentioned in the corresponding release notes. That applies to both testing and stable versions. A warning to check release notes is already included.

We currently don't mention nightly builds anywhere in the documentation (only cloud touches on it). Even the tarball installation instructions point straight to regular releases. Hence my tendency to ignore it here as well to keep the guide focused.

Removed a warning that upgrades aren't possible from "testing versions". This is not applicable if we understand "testing versions" as the testing channel, which are regular releases. It may have targeted nightly builds, but those aren't supported anyway.