Upgrade rewrites for v24.3

- [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

src/current/_includes/common/upgrade/disable-auto-finalization.md

@@ -0,0 +1,20 @@
+By default, auto-finalization is enabled, and a major-version upgrade is finalized when all nodes have rejoined the cluster using the new `cockroach` binary. This means that by default, a major-version upgrade cannot be rolled back. Instead, you must [restore the cluster to the previous version]({% link {{ page.version.version }}/restoring-backups-across-versions.md %}#support-for-restoring-backups-into-a-newer-version).
+
+To disable auto-finalization:
+
+1. Connect to the cluster using the SQL shell:
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ shell
+    cockroach sql
+    ~~~
+
+1. Set the [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) `cluster.auto_upgrade.enabled` to `false`.
+
+Now, to complete a major-version upgrade, you must manually [finalize it](#finalize-a-major-version-upgrade) or [roll it back]({#roll-back-a-major-version-upgrade).
+
+{{site.data.alerts.callout_info}}
+Previously, to disable automatic finalization and preserve the ability to roll back a major-version upgrade, it was required to set the cluster setting `cluster.preserve_downgrade_option` to the cluster's current major version before beginning the major-version upgrade. This cluster setting does not persist after finalization is complete, but must be set before each major-version upgrade.
+
+We now recommend managing a cluster's finalization policy using the cluster setting `cluster.auto_upgrade.enabled`, which was introduced in v23.2 and persists after finalization is complete. Either of these settings prevents automatic finalization.
+{{site.data.alerts.end}}

src/current/_includes/common/upgrade/finalize-cloud.md

@@ -0,0 +1,10 @@
+To finalize a major-version upgrade manually,
+
+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.
+
+    You can monitor the process of finalization in the CockroachDB {{ site.data.products.cloud }} [Jobs page]({% link cockroachcloud/jobs-page.md %}). Migration jobs have names in the format `{major-version}-{migration-id}`. If a migration job fails or stalls, Cockroach Labs can use the migration ID to help diagnose and troubleshoot the problem. Each major version has a unique set of migration jobs and IDs.
+
+When finalization is complete, the **Cluster List** and **Cluster Details** page report the new version, and you can no longer roll back to the previous major version.

src/current/_includes/common/upgrade/finalize-self-hosted.md

@@ -0,0 +1,36 @@
+To finalize a major-version upgrade, run the following command. Replace `{VERSION}` new major version, such as `{{ page.version.version }}:
+
+1. Connect to the cluster using the SQL shell:
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ shell
+    cockroach sql
+    ~~~
+
+1. Run the following command. Replace `{VERSION}` with the new major version, such as `{{ page.version.version }}`.
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ shell
+    SET CLUSTER SETTING version '{VERSION}';
+    ~~~
+
+    A series of migration jobs runs 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. Until the upgrade is finalized, these features and functions will not be available and the command `SHOW CLUSTER SETTING version` will return `{{ previous_version_numeric }}`.
+
+    You can monitor the process of the migration in the DB Console [Jobs page]({% link {{ page.version.version }}/ui-jobs-page.md %}). Migration jobs have names in the format `{{ major_version_numeric }}-{migration-id}`. If a migration job fails or stalls, Cockroach Labs can use the migration ID to help diagnose and troubleshoot the problem. Each major version has different migration jobs with different IDs.
+
+    The amount of time required for finalization depends on the amount of data in the cluster, because finalization runs various internal maintenance and migration tasks. During this time, the cluster will experience a small amount of additional load.
+
+    {{site.data.alerts.callout_info}}
+    Finalization is not complete until all [schema change]({% link {{ page.version.version }}/online-schema-changes.md %}) jobs reach a terminal state. Finalization can take as long as the longest-running schema change.
+    {{site.data.alerts.end}}
+
+    When all migration jobs have completed, the upgrade is complete.
+
+1. To confirm that finalization has completed, check the cluster version:
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ sql
+    > SHOW CLUSTER SETTING version;
+    ~~~
+
+    If the cluster continues to report that it is on the previous version, finalization has not completed. If auto-finalization is enabled but finalization has not completed, check for the existence of [decommissioning nodes]({% link {{ page.version.version }}/node-shutdown.md %}?filters=decommission#status-change) where decommission has stalled. In most cases, issuing the `decommission` command again resolves the issue. If you have trouble upgrading, [contact Support](https://cockroachlabs.com/support/hc/).

src/current/_includes/common/upgrade/major-version-upgrade-cloud.md

@@ -0,0 +1,21 @@
+This section shows how to perform a major-version upgrade for a cluster in CockroachDB {{ site.data.products.cloud }}. Patch upgrades within a cluster's major version are applied automatically, and no action is required.
+
+1. Verify the cluster's current major version, and which versions it can be upgraded to:
+    1. Sign into [CockroachDB {{ site.data.products.cloud }}](https://cockroachlabs.cloud).
+    1. From the **Clusters** page, find the cluster by name. If the cluster is in a folder, click the name of the folder to view its descendants. The cluster's major version and patch are shown in the **Version** column.
+1. Check which upgrades are available to the cluster, if any.
+
+    Beginning with v24.1, major versions alternate in type between Regular releases, which are required, and Innovation releases, which can be skipped.
+
+    From a Regular release, you can upgrade to the next major release (an Innovation release) or the subsequent major release (another Regular release). From an Innovation release, you must upgrade to the next Regular release.
+
+    These releases also provide different support periods.
+
+    For details, refer the [CockroachDB Cloud Support Policy]({% link cockroachcloud/upgrade-policy.md %}#cockroachdb-cloud-support-policy).
+
+    To check whether major-version upgrades are available, click the three-dot **Action** menu. If upgrades are available, **Upgrade major version** will be enabled. Click it. In the dialog, if only one newer major version upgrade is available, it is selected automatically. If multiple upgrades are available, the latest Regular release is selected by default. If you intend to upgrade the cluster, keep this dialog open while completing the next steps. Otherwise, close the dialog.
+1. Before beginning a major-version upgrade, review its [Release notes]({% link releases/index.md %}), as well as the release notes for any skipped Innovation Releases. If any backward-incompatible changes or new features impact the cluster's workloads, you may need to make adjustments before beginning the upgrade.
+1. A CockroachDB {{ site.data.products.standard }} or {{ site.data.products.basic }} cluster remains fully available while it is upgraded. For a multi-node CockroachDB {{ site.data.products.advanced }} cluster, nodes are upgraded one at a time in a rolling fashion so the cluster remains available, with one node unavailable at a time. A single-node {{ site.data.products.advanced }} cluster will be unavailable while the cluster is upgraded and restarted. If necessary, prepare for the upgrade by communicating ahead of time with your users, and plan to begin the upgrade during a time when the impact on the cluster's workload will be minimized.
+1. To begin a major-version upgrade, go back to the dialog in the CockroachDB {{ site.data.products.cloud }} Console. If multiple upgrades are available, select the desired version. Review the details, then click **Start upgrade**. The dialog closes, and the **Version** columnin the **Cluster List** page changes to **Upgrading**. When the upgrade has finished but has not yet been finalized, the **Version** column reports that the new version is **pending**.
+
+The upgrade is not complete until it is [finalized](#finalize-a-major-version-upgrade). After the upgrade is finalized, the cluster can no longer be [rolled back](#roll-back-a-major-version-upgrade) to its previous major version. If you take no action, finalization occurs automatically after approximately 72 hours.

src/current/_includes/common/upgrade/major-version-upgrade-self-hosted.md

@@ -0,0 +1,15 @@
+To perform a major upgrade:
+
+1. One node at a time:
+    1. Replace the `cockroach` binary on the node with the binary for the new patch release. For containerized workloads, update the deployment to use the image for the new patch release.
+    1. Restart CockroachDB on the node. For containerized workloads, use your orchestration framework to restart the `cockroach` process in the node's container.
+    1. Ensure that the node is ready to accept a SQL connection. Unless there are tens of thousands of [ranges]({% link {{ page.version.version }}/architecture/overview.md %}#architecture-range) on the node, this takes less than a minute.
+
+        To be certain that the node is ready, run the following command to connect to the cluster and run a test query.
+
+        {% include_cached copy-clipboard.html %}
+        ~~~ shell
+        cockroach sql -e 'select 1'
+        ~~~
+1. If auto-finalization is enabled (the default), finalization begins as soon as the last node rejoins the cluster with the new binary. When finalization finishes, the upgrade is complete.
+1. If auto-finalization is disabled, follow your organization's testing procedures to decide whether to [finalize the upgrade](#finalize-a-major-version-upgrade) or [roll back](#roll-back-a-major-version-upgrade) the upgrade. After finalization begins, you can no longer roll back to the cluster's previous major version.

src/current/_includes/common/upgrade/overview.md

@@ -0,0 +1,10 @@
+CockroachDB offers the following types of upgrades:
+
+- [**Major-version upgrades**]({% link releases/index.md %}#major-releases): A major-version upgrade moves a cluster from one major version of CockroachDB to another, such as from v24.2 to v24.3. A major-version upgrade may include new features, updates to cluster setting defaults, and backward-incompatible changes. Performing a major-version upgrade requires an additional step to finalize the upgrade.
+
+    As of 2024, every second major version is an **Innovation release**. {% if page.path contains "cockroachcloud" %}For CockroachDB {{ site.data.products.standard }} and CockroachDB {{ site.data.products.advanced }},innovation{% else %}Innovation{% endif %} releases offer shorter support windows and can be skipped. {% if page.path contains "cockroachcloud" %}Innovation releases are required for CockroachDB {{ site.data.products.basic }}, and are applied automatically.{% endif %}
+- [**Patch upgrades**]({% link releases/index.md %}#patch-releases): A patch upgrade moves a cluster from one patch to another within a major version, such as from v24.2.3 to v24.2.4. Patch upgrades do not introduce backward-incompatible changes. {% if page.path contains "cockroachcloud" %}Patch upgrades are automatically applied to CockroachDB {{ site.data.products.advanced }}, {{ site.data.products.standard }}, and {{ site.data.products.basic }} clusters.{% endif %}
+
+    A major version of CockroachDB has two phases of patch releases: a series of **testing releases** followed by a series of **production releases**. A major version’s initial production release is also known as its GA release. In the lead-up to a new major version's GA release, a series of Testing releases may be made available{% if page.path contains "cockroachcloud" %} to CockroachDB {{ site.data.products.advanced }} as Pre-Production Preview releases{% endif %} for testing and validation. Testing releases are intended for testing and experimentation only, and are not qualified for production environments or eligible for support or uptime SLA commitments. {% if page.path contains "cockroachcloud" %}If a cluster is upgraded to a Pre-Production Preview patch release, it will be automatically upgraded to subsequent patch releases within the major version, including newer Pre-Production Preview releases, the initial GA release, and subsequent patch releases.{% else %}{{site.data.alerts.callout_info}}A cluster cannot be upgraded from an alpha binary of a prior release or from a binary built from the `master` branch of the CockroachDB source code.{{site.data.alerts.end}}{% endif %}
+
+To learn more about CockroachDB major versions and patches, refer to the [Releases Overview]({% link releases/index.md %}#overview).

src/current/_includes/common/upgrade/patch-rollback-self-hosted.md

@@ -0,0 +1 @@
+To roll back a patch upgrade, repeat the steps in [Perform a patch upgrade](#perform-a-patch-upgrade), but replace the newer binary with the older version.

src/current/_includes/common/upgrade/patch-upgrade-self-hosted.md

@@ -0,0 +1,15 @@
+To upgrade from one patch release to another within the same major version, perform the following steps on one node at a time:
+
+1. Replace the `cockroach` binary on the node with the binary for the new patch release. For containerized workloads, update the deployment's image to the image for the new patch release.
+1. Restart CockroachDB on the node.
+1. Verify that the node has rejoined the cluster.
+1. Ensure that the node is ready to accept a SQL connection.
+
+        Unless there are tens of thousands of ranges on the node, it's usually sufficient to wait one minute. To be certain that the node is ready, run the following command:
+
+        {% include_cached copy-clipboard.html %}
+        ~~~ shell
+        cockroach sql -e 'select 1'
+        ~~~
+
+When all nodes are running the new patch version, the upgrade is complete.

src/current/_includes/common/upgrade/prepare-to-upgrade-cloud.md

@@ -0,0 +1,12 @@
+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#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.
+
+        If any node is not fully decommissioned, try the following:
+            1. First, reissue the [decommission command]({% link {{ site.current_cloud_version }}/node-shutdown.md %}?filters=decommission#decommission-the-node). The second command typically succeeds within a few minutes.
+            1. If the second decommission command does not succeed, [recommission]({% link {{ site.current_cloud_version }}/node-shutdown.md %}?filters=decommission#recommission-nodes) and then decommission it again. Before continuing the upgrade, the node must be marked as `decommissioned`.
+    - Under **Replication Status**, make sure there are `0` under-replicated and unavailable ranges. Otherwise, performing a rolling upgrade increases the risk that ranges will lose a majority of their replicas and cause cluster unavailability. Therefore, it's important to identify and resolve the cause of range under-replication and/or unavailability before beginning your upgrade.
+1. Review the cluster's [Metrics page]({% link cockroachcloud/metrics.md %}) to ensure that your cluster's compute and storage capacity is within acceptable values. The cluster must be able to tolerate some increase, in case the new version uses more resources for your workload. If any of these metrics is above healthy limits, consider increasing the cluster's resources before beginning your upgrade.
+1. {% include {{ site.current_cloud_version }}/backups/recommend-backups-for-upgrade.md %}
+1. Review the [{{ site.current_cloud_version }} Release Notes]({% link releases/{{ site.current_cloud_version }}.md %}), as well as the release notes for any skipped major version. Pay careful attention to the sections for backward-incompatible changes, deprecations, changes to default cluster settings, and features that are not available until the upgrade is finalized.