Upgrade rewrites for v24.3 #19098
Open
Upgrade rewrites for v24.3 #19098
+824
−949
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Files changed:
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
|
@dcrosta Please review the Cloud upgrade page (or nominate another reviewer) The bulk of this PR is modularizing the content into includes to build up both the self-hsoted and Cloud pages. It may be simpler to rely on the HTML previews to do the reviews. |
❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →
|
mdlinville
force-pushed
the
DOC-11170
branch
2 times, most recently
from
05fb164
to
70f6b55
Compare
- [DOC-11170] Document version skipping - [DOC-8495] Incorrect details about alpha releases - [DOC-8412] Add details about monitoring upgrade progress - [DOC-11046] Discuss major and minor version upgrades separately - [DOC-11650] v24.3 upgrade instructions - Modularize Cloud and CRDB upgrade pages to use includes - Reduce version-specific details in upgrade pages
mdlinville
force-pushed
the
DOC-11170
branch
2 times, most recently
from
c6a2c68
to
90ec1bd
Compare
dcrosta
reviewed
Nov 6, 2024
| 1. Click the cluster's name to open the **Cluster Details** page. | ||
| 1. At the top of the page, click **Finalize**. | ||
|
|
||
| When finalization begins, a series of migration jobs run to enable certain types of features and changes in the new major version that cannot be rolled back. These include changes to system schemas, indexes, and descriptors, and enabling certain types of improvements and new features. These temporary limitations are listed in the release notes for the new major version. Until the upgrade is finalized, these features and functions will not be available and the command `SHOW CLUSTER SETTING version` will continue to report the previous major version. |
There was a problem hiding this comment.
The "These temporary limitations" sentence feels like it belongs in its own paragraph, with a statement that there are temporary limits.
| Before beginning a major-version upgrade: | ||
|
|
||
| 1. **CockroachDB {{ site.data.products.advanced }}**: Verify the overall health of your cluster using the [DB Console]({% link cockroachcloud/tools-page.md %}#access-the-db-console.md): | ||
| - Under **Node Status**, make sure all nodes that should be live are listed as such. If any nodes are unexpectedly listed as `SUSPECT` or `DEAD`, identify why the nodes are offline and either restart them or [decommission]({% link {{ site.current_cloud_version }}/node-shutdown.md %}?filters=decommission#remove-nodes) them before beginning your upgrade. If there are `DEAD` and non-decommissioned nodes in your cluster, the upgrade cannot be finalized. |
There was a problem hiding this comment.
@joshimhoff can you comment on whether this is something cloud customers need to do? Does our automation ever allow suspect or dead nodes to stick around?
| 1. Click the cluster's name to open the **Cluster Details** page. | ||
| 1. At the top of the page, click **Roll back**. | ||
|
|
||
| A CockroachDB {{ site.data.products.standard }} or {{ site.data.products.basic }} cluster remains fully available while it is rolled back. For a multi-node CockroachDB {{ site.data.products.advanced }} cluster, nodes are rolled back one at a time in a rolling fashion so the cluster remains available, with one node unavailable at a time. A single-node CockroachDB {{ site.data.products.advanced }} cluster will be unavailable while the cluster is rolled back and restarted. Like an upgrade, a rollback must be finalized. |
There was a problem hiding this comment.
@mdlinville Basic clusters cannot be rolled back by the user -- CRL controls upgrades on basic clusters, users neither get to choose when they happen nor to roll back
| 1. At the top of the page, click **Roll back**. | ||
|
|
||
| A CockroachDB {{ site.data.products.standard }} or {{ site.data.products.basic }} cluster remains fully available while it is rolled back. For a multi-node CockroachDB {{ site.data.products.advanced }} cluster, nodes are rolled back one at a time in a rolling fashion so the cluster remains available, with one node unavailable at a time. A single-node CockroachDB {{ site.data.products.advanced }} cluster will be unavailable while the cluster is rolled back and restarted. Like an upgrade, a rollback must be finalized. | ||
| 1. Like a major-version upgrade, a rollback must be [finalized](#finalize-a-major-versino-upgrade). When the rollback is finalized, the rollback is complete. |
There was a problem hiding this comment.
Suggested change
| 1. Like a major-version upgrade, a rollback must be [finalized](#finalize-a-major-versino-upgrade). When the rollback is finalized, the rollback is complete. |
| 1. Click the cluster's name to open the **Cluster Details** page. | ||
| 1. At the top of the page, click **Roll back**. | ||
|
|
||
| A CockroachDB {{ site.data.products.standard }} or {{ site.data.products.basic }} cluster remains fully available while it is rolled back. For a multi-node CockroachDB {{ site.data.products.advanced }} cluster, nodes are rolled back one at a time in a rolling fashion so the cluster remains available, with one node unavailable at a time. A single-node CockroachDB {{ site.data.products.advanced }} cluster will be unavailable while the cluster is rolled back and restarted. Like an upgrade, a rollback must be finalized. |
There was a problem hiding this comment.
Suggested change
| A CockroachDB {{ site.data.products.standard }} or {{ site.data.products.basic }} cluster remains fully available while it is rolled back. For a multi-node CockroachDB {{ site.data.products.advanced }} cluster, nodes are rolled back one at a time in a rolling fashion so the cluster remains available, with one node unavailable at a time. A single-node CockroachDB {{ site.data.products.advanced }} cluster will be unavailable while the cluster is rolled back and restarted. Like an upgrade, a rollback must be finalized. | |
| A CockroachDB {{ site.data.products.standard }} or {{ site.data.products.basic }} cluster remains fully available while it is rolled back. For a multi-node CockroachDB {{ site.data.products.advanced }} cluster, nodes are rolled back one at a time in a rolling fashion so the cluster remains available, with one node unavailable at a time. A single-node CockroachDB {{ site.data.products.advanced }} cluster will be unavailable while the cluster is rolled back and restarted. |
Roll back doesn't require an additional user step after they click the button the first time -- there is no finalization for rollback.
|
|
||
| To learn more about CockroachDB major versions and patches, refer to the [Releases Overview]({% link releases/index.md %}#overview). | ||
| For CockroachDB {{ site.data.products.standard }} and CockroachDB {{ site.data.products.basic }}, a cluster's resources are not impacted by an ongoing upgrade. |
There was a problem hiding this comment.
Suggested change
| For CockroachDB {{ site.data.products.standard }} and CockroachDB {{ site.data.products.basic }}, a cluster's resources are not impacted by an ongoing upgrade. | |
| For CockroachDB {{ site.data.products.standard }} and CockroachDB {{ site.data.products.basic }}, a cluster remains available during an upgrade. |
or something like this?
| ## Upgrades and maintenance windows | ||
|
|
||
| If you have [configured a maintenance window]({% link cockroachcloud/advanced-cluster-management.md %}) for a CockroachDB {{ site.data.products.advanced }} cluster, automatic patch upgrades are applied during the maintenance window. Major-version upgrades must be initiated manually. | ||
| For CockroachDB {{ site.data.products.advanced }}, nodes are upgraded one at a time in a rolling fashion, and the cluster's resources are reduced as each node is upgraded. If you have [configured a maintenance window]({% link cockroachcloud/advanced-cluster-management.md %}) for a CockroachDB {{ site.data.products.advanced }} cluster, automatic patch upgrades are applied during the maintenance window. Major-version upgrades must be initiated manually. |
There was a problem hiding this comment.
Suggested change
| For CockroachDB {{ site.data.products.advanced }}, nodes are upgraded one at a time in a rolling fashion, and the cluster's resources are reduced as each node is upgraded. If you have [configured a maintenance window]({% link cockroachcloud/advanced-cluster-management.md %}) for a CockroachDB {{ site.data.products.advanced }} cluster, automatic patch upgrades are applied during the maintenance window. Major-version upgrades must be initiated manually. | |
| For CockroachDB {{ site.data.products.advanced }}, nodes are upgraded one at a time in a rolling fashion. Multi-node clusters will remain available during the upgrade, but will have reduced capacity as each node restarts. Single-node clusters will be unavailable while the node restarts. | |
| ## Upgrades and maintenance windows | |
| If you have [configured a maintenance window]({% link cockroachcloud/advanced-cluster-management.md %}) for a CockroachDB {{ site.data.products.advanced }} cluster, automatic patch upgrades are applied during the maintenance window. Major-version upgrades must be initiated manually. |
I suggest restoring the heading, as it leads into the following paragraph/callout as well.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Upgrade rewrites for v24.3
Previews
Cloud: src/current/cockroachcloud/upgrade-cockroach-version.md
Self-hosted: src/current/v24.3/upgrade-cockroach-version.md
Self-hosted Kubernetes: src/current/v24.3/upgrade-cockroachdb-kubernetes.md