From 5ad2b98acd316609cebff7db0b6a6b55f5d3c034 Mon Sep 17 00:00:00 2001 From: Mike Lewis <76072290+mikeCRL@users.noreply.github.com> Date: Fri, 9 Aug 2024 19:58:04 -0400 Subject: [PATCH] Content updates for Innovation releases (#18801) --------- Co-authored-by: Matt Linville --- src/current/_config_cockroachdb.yml | 4 +- .../_includes/releases/v20.1/v20.1.0.md | 2 +- src/current/cockroachcloud/authorization.md | 2 +- src/current/cockroachcloud/upgrade-policy.md | 94 ++++++---- .../cockroachcloud/upgrade-to-v23.2.md | 2 +- .../cockroachcloud/upgrade-to-v24.1.md | 3 +- .../cockroachcloud/upgrade-to-v24.2.md | 169 ++++++++++++++++++ src/current/releases/index.md | 147 +++++++++++---- .../releases/release-support-policy.md | 71 +++++--- 9 files changed, 399 insertions(+), 95 deletions(-) create mode 100644 src/current/cockroachcloud/upgrade-to-v24.2.md diff --git a/src/current/_config_cockroachdb.yml b/src/current/_config_cockroachdb.yml index 06587c7afed..f1eae8a8873 100644 --- a/src/current/_config_cockroachdb.yml +++ b/src/current/_config_cockroachdb.yml @@ -1,7 +1,7 @@ baseurl: /docs -current_cloud_version: v24.1 +current_cloud_version: v24.2 destination: _site/docs homepage_title: CockroachDB Docs versions: - stable: v24.1 + stable: v24.2 dev: v24.2 diff --git a/src/current/_includes/releases/v20.1/v20.1.0.md b/src/current/_includes/releases/v20.1/v20.1.0.md index 23e625c2ea7..f2bdcefba92 100644 --- a/src/current/_includes/releases/v20.1/v20.1.0.md +++ b/src/current/_includes/releases/v20.1/v20.1.0.md @@ -130,4 +130,4 @@ Docs | **"Hello World" Repos** | Added several language-specific [GitHub repos]( Docs | **Multi-Region Sample App and Tutorial** | Added a full-stack, multi-region sample application ([GitHub repo](https://github.com/cockroachlabs/movr-flask)) with an [accompanying tutorial](https://www.cockroachlabs.com/docs/v20.1/multi-region-overview) on building a multi-region application on a multi-region CockroachCloud cluster. Also added a [video demonstration](https://www.youtube.com/playlist?list=PL_QaflmEF2e8o2heLyIt5iDUTgJE3EPkp) as a YouTube playlist. Docs | **Streaming Changefeeds to Snowflake Tutorial** | Added an [end-to-end tutorial](https://www.cockroachlabs.com/docs/cockroachcloud/stream-changefeed-to-snowflake-aws) on how to use an Enterprise changefeed to stream row-level changes from CockroachCloud to Snowflake, an online analytical processing (OLAP) database. Docs | **Improved Backup/Restore Docs** | Updated the backup/restore docs to better separate [broadly applicable guidance and best practices](https://www.cockroachlabs.com/docs/v20.1/backup-and-restore) from more advanced topics. -Docs | **Release Support Policy** | Added a page explaining Cockroach Labs' [policy for supporting major releases of CockroachDB]({% link releases/release-support-policy.md %}), including the phases of support that each major release moves through, the currently supported releases, and an explanation of the [naming scheme]({% link releases/index.md %}#release-naming) used for CockroachDB. +Docs | **Release Support Policy** | Added a page explaining Cockroach Labs' [policy for supporting major releases of CockroachDB]({% link releases/release-support-policy.md %}), including the phases of support that each major release moves through, the currently supported releases, and an explanation of the [naming scheme]({% link releases/index.md %}#overview) used for CockroachDB. diff --git a/src/current/cockroachcloud/authorization.md b/src/current/cockroachcloud/authorization.md index a491f32487a..0ae5620a451 100644 --- a/src/current/cockroachcloud/authorization.md +++ b/src/current/cockroachcloud/authorization.md @@ -82,7 +82,7 @@ Cluster Operators can perform a variety of cluster functions: - View a cluster's Jobs from the [Jobs page]({% link cockroachcloud/jobs-page.md %}). - View a cluster's Metrics from the [Metrics page]({% link cockroachcloud/metrics-page.md %}). - View a cluster's Insights from the [Insights page]({% link cockroachcloud/insights-page.md %}). - - [Upgrade]({% link cockroachcloud/upgrade-to-v23.1.md %}#step-5-start-the-upgrade) a cluster's CRDB version. + - [Upgrade]({% link cockroachcloud/upgrade-to-{{site.current_cloud_version}}.md %}) a cluster's CockroachDB version. - View a cluster's [PCI-readiness status (Dedicated Advanced clusters only)]({% link cockroachcloud/cluster-overview-page.md %}?filters=dedicated#pci-ready-dedicated-advanced). - Send a test alert from the [Alerts Page]({% link cockroachcloud/alerts-page.md %}). - Configure single sign-on (SSO) enforcement. diff --git a/src/current/cockroachcloud/upgrade-policy.md b/src/current/cockroachcloud/upgrade-policy.md index 3ac7718365d..93085809d44 100644 --- a/src/current/cockroachcloud/upgrade-policy.md +++ b/src/current/cockroachcloud/upgrade-policy.md @@ -5,64 +5,98 @@ toc: true docs_area: manage --- -This page describes the support and upgrade policy for clusters deployed in CockroachDB {{ site.data.products.cloud }}. For CockroachDB Self-Hosted, refer to the CockroachDB [Release Support Policy](https://www.cockroachlabs.com/docs/releases/release-support-policy). +This page describes the support and upgrade policy for clusters deployed in CockroachDB {{ site.data.products.cloud }}. For CockroachDB {{ site.data.products.core }}, refer to the CockroachDB [Release Support Policy]({% link releases/release-support-policy.md %}). -Cockroach Labs uses a three-component calendar versioning scheme to name CockroachDB [releases](https://cockroachlabs.com/docs/releases/index#production-releases). The format is `YY.R.PP`, where `YY` indicates the year, `R` indicates the release (historically “1” or “2”, representing a biannual cycle), and `PP` indicates the patch release version. For example: Version 23.1.0 (abbreviated v23.1.0). Leading up to a new major version's initial GA (Generally Available) release, multiple testing builds are produced, moving from Alpha to Beta to Release Candidate. CockroachDB began using this versioning scheme with v19.1. For more details, refer to [Release Naming](https://cockroachlabs.com/docs/releases/index#release-naming). +## CockroachDB Cloud Support Policy -CockroachDB {{ site.data.products.cloud }} provides support for the latest major version of CockroachDB and the major version immediately preceding it. +[Major versions]({% link releases/index.md %}) of CockroachDB are labeled either [Regular releases]({% link releases/index.md %}#major-releases) or [Innovation releases]({% link releases/index.md %}). +- **Regular releases** are supported for 12 months from their initial production release date. +- **Innovation releases** are supported for 6 months from their initial production release date. -CockroachDB Dedicated clusters are automatically upgraded to the latest patch of the cluster’s current major version of CockroachDB, but an account administrator must initiate an upgrade to a new major version. +For each release type, the end date of this period is called End of Support (EOS). -CockroachDB Serverless clusters are upgraded to the latest major version and each patch automatically. +A cluster running an unsupported CockroachDB version is not eligible for Cockroach Labs’ [availability SLA](https://www.cockroachlabs.com/cloud-terms-and-conditions/cockroachcloud-technical-service-level-agreement/). -{{site.data.alerts.callout_success}} -Prior to the GA release of a major CockroachDB version, CockroachDB {{ site.data.products.dedicated }} clusters can optionally be upgraded to a [Pre-Production Preview](#pre-production-preview-upgrades) release—a beta or release candidate (RC) testing release for testing and validation of that next major version. To learn more, refer to [Upgrade to v24.1 Pre-Production Preview]({% link cockroachcloud/upgrade-to-v24.1.md %}). -{{site.data.alerts.end}} +CockroachDB {{ site.data.products.serverless }} clusters will automatically be upgraded to the next major version while the current one is still supported, to prevent a Serverless cluster from reaching EOS. -## Patch version upgrades +A CockroachDB {{ site.data.products.dedicated }} cluster must be upgraded prior to its EOS date to maintain uninterrupted support and SLA guarantees. + +When a CockroachDB {{ site.data.products.dedicated }} cluster is nearing its EOS date, you will be reminded to upgrade the cluster at least 30 days before the EOS date to avoid losing support. {% capture who_can_upgrade %}A [Cluster Administrator]({% link cockroachcloud/authorization.md %}#cluster-administrator) can [upgrade a cluster]({% link cockroachcloud/upgrade-to-{{site.current_cloud_version}}.md %}) directly from the CockroachDB Cloud Console. An [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) or [Folder Admin]({% link cockroachcloud/authorization.md %}#folder-admin) can grant the Cluster Administrator role.{% endcapture %}{{ who_can_upgrade }} + +### Currently supported versions + +Version | Release Type | Support period | Release date | EOS date +:------:|:------------:|:--------------:|:------------:|:---------: +v23.2 | Regular | 12 months | 2024-02-05 | 2025-02-05 +v24.1 | Regular | 12 months | 2024-05-20 | 2025-05-20 +v24.2 | Innovation | 6 months | 2024-08-12 | 2025-02-12 + +For expected future versions, refer to [Upcoming releases]({% link releases/index.md %}#upcoming-releases). -Patch version [releases](https://www.cockroachlabs.com/docs/releases), or "maintenance" releases, contain stable, backward-compatible improvements to the major versions of CockroachDB (for example, v23.1.12 and v23.1.13). +### EOS versions -For CockroachDB {{ site.data.products.dedicated }} clusters, [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) can [set a weekly 6-hour maintenance window]({% link cockroachcloud/cluster-management.md %}#set-a-maintenance-window) during which available patch upgrades will be applied. During the window, your cluster may experience restarts, degraded performance, and, for single-node clusters, downtime. Upgrades may not always be completed by the end of the window, and maintenance that is critical for security or stability may occur outside the window. Patch upgrades can also be [deferred for 60 days]({% link cockroachcloud/cluster-management.md %}#set-a-maintenance-window). If no maintenance window is configured, CockroachDB {{ site.data.products.dedicated }} clusters will be automatically upgraded to the latest supported patch version as soon as it becomes available. +Version | Release Type | Support period | Release date | EOS date +:------:|:------------:|:--------------:|:------------:|:--------: +|v23.1 | Regular | 12 months | 2023-05-15 | 2024-05-15 -CockroachDB {{ site.data.products.serverless }} clusters are subject to automatic upgrades to the latest supported patch version. +## Patch version upgrades + +A patch version [release]({% link releases/index.md %}), or "maintenance" releases, contains stable, backward-compatible improvements to a major version of CockroachDB. For example, {{site.current_cloud_version}} is a patch release. {{site.data.alerts.callout_danger}} -Single-node clusters will experience some downtime during cluster maintenance. +Single-node clusters will experience some downtime while the node is restarted during cluster maintenance, including patch version upgrades. {{site.data.alerts.end}} + +## CockroachDB {{ site.data.products.dedicated }} patch upgrades and maintenance windows + +CockroachDB {{ site.data.products.dedicated }} clusters are automatically upgraded to the latest patch version release of the cluster’s current CockroachDB major version, but a major-version upgrade must be initiated by an Org Administrator. + +A [Cluster Administrator]({% link cockroachcloud/authorization.md %}#cluster-administrator) can [set a weekly 6-hour maintenance window]({% link cockroachcloud/cluster-management.md %}#set-a-maintenance-window) for a CockroachDB {{ site.data.products.dedicated }} cluster. During the maintenance window, patch upgrades may be applied, and the cluster may experience restarts, degraded performance, and, for single-node clusters, downtime. Upgrades may not always be completed by the end of the window, and maintenance that is critical for security or stability may occur outside of the window. A patch upgrade can be [deferred for 60 days]({% link cockroachcloud/cluster-management.md %}#set-a-maintenance-window). If no maintenance window is configured, a CockroachDB {{ site.data.products.dedicated }} cluster will be upgraded automatically to the latest supported patch version soon after it becomes available. + +### CockroachDB {{ site.data.products.serverless }} automatic upgrades + +CockroachDB {{ site.data.products.serverless }} clusters are automatically upgraded to new patch versions, as well as new major versions. + ## Major version upgrades -Major version [releases](https://www.cockroachlabs.com/docs/releases) (for example, v23.1.0 and v23.2.0) contain new functionality and may include backward-incompatible changes to CockroachDB. +Major version [releases](https://www.cockroachlabs.com/docs/releases) (for example, {{ site.current_cloud_version }}) contain new functionality and may include backward-incompatible changes to CockroachDB. -Major version upgrades are automatic for CockroachDB {{ site.data.products.serverless }} clusters and opt-in for CockroachDB {{ site.data.products.dedicated }} clusters. An [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) must initiate major version upgrades for CockroachDB {{ site.data.products.dedicated }} clusters. When a new major version is available, Admins will be able to [start an upgrade]({% link cockroachcloud/upgrade-to-v23.1.md %}) from the CockroachDB {{ site.data.products.cloud }} Console for clusters using CockroachDB {{ site.data.products.dedicated }}. When a major version upgrade is initiated for a cluster, it will upgrade to the latest patch version as well. +Major version upgrades are automatic for CockroachDB {{ site.data.products.serverless }} clusters and must be initiated by an [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) for CockroachDB {{ site.data.products.dedicated }} clusters. In CockroachDB {{ site.data.products.dedicated }}, major versions labeled Regular releases are all required upgrades, while Innovation releases are optional. Once a new major version is available, you can [start an upgrade]({% link cockroachcloud/upgrade-to-{{site.current_cloud_version}}.md %}) from the CockroachDB Cloud Console. The cluster will be upgraded to the latest patch release within that major version. -### Pre-production preview upgrades +### Innovation releases -Prior to the GA release of a major CockroachDB version, CockroachDB {{ site.data.products.cloud }} organizations can create new {{ site.data.products.dedicated }} clusters or upgrade existing clusters to a Pre-Production Preview release for testing and experimentation using a beta or release candidate (RC) of that next major version. Upgrading to a Pre-Production Preview is a major-version upgrade. After a cluster is upgraded to a Pre-Production Preview release, it is automatically upgraded to all subsequent releases within the same major version—including additional beta and RC releases, the GA release, and subsequent patch releases after GA, as [patch version upgrades](#patch-version-upgrades). To learn more, refer to [Upgrade to v23.2 Pre-Production Preview](https://cockroachlabs.com/docs/cockroachcloud/upgrade-to-v24.1). +As of v24.2, Cockroach Labs releases a major version of CockroachDB once per quarter, alternating between releases classified as a [Regular release or an Innovation release]({% link releases/index.md %}#release-types). Regular releases provide a longer support period and a longer period between upgrades, while Innovation releases offer a shorter support period and faster access to new features. -### Rollback support +- Regular releases are not optional; they must be applied to CockroachDB {{ site.data.products.dedicated }} clusters and they are applied automatically to CockroachDB {{ site.data.products.serverless }} clusters. Regular releases are produced twice a year, alternating with Innovation Releases. They are supported for one year. Upgrading CockroachDB {{ site.data.products.dedicated }} directly from one regular release to the next regular release, skipping the intervening Innovation release, is supported. +- Innovation releases are optional and can be skipped for CockroachDB {{ site.data.products.dedicated }} clusters but are required for CockroachDB {{ site.data.products.serverless }}. Innovation releases are produced twice a year, alternating with Regular releases. An innovation release is supported for 6 months, at which time a Dedicated cluster must be upgraded to the next Regular Release. At a given time, only one Innovation release is typically supported. Upgrading CockroachDB {{ site.data.products.dedicated }} directly from one Innovation release to the next Innovation release is not supported. -When upgrading a CockroachDB {{ site.data.products.dedicated }} cluster to a new major version, once all nodes are running the new version, you have approximately 72 hours before the upgrade is automatically finalized. During this window, if you see unexpected behavior, you can trigger a rollback to the previous major version from the CockroachDB {{ site.data.products.cloud }} Console. +{{site.data.alerts.callout_info}} +To opt out of Innovation releases entirely and hide them from your CockroachDB organization, contact Support.{{site.data.alerts.end}} -To stop the upgrade and roll back to the latest patch release of the previous major version, click **Roll back** in the banner at the top of the CockroachDB Cloud Console, and then click **Roll back upgrade**. +To summarize the available major-version upgrade paths for CockroachDB {{ site.data.products.dedicated }}: -{{site.data.alerts.callout_danger}} -If you choose to roll back a major version upgrade, your cluster will be rolled back to the latest patch release of the previous major version, which may differ from the patch release you were running before you initiated the upgrade. -{{site.data.alerts.end}} +- When your cluster is running a Regular release, you can select which of the next two major versions to upgrade to: + - The next version, an Innovation release. + - The Regular release that follows that Innovation release, when it is available. +- When your cluster is running an Innovation release, you can upgrade only to the subsequent Regular release, not directly to the newer Innovation release, if it is available. + +### Pre-production preview upgrades -During rollback, nodes are reverted to that prior major version's latest patch one at a time, without interrupting the cluster's health and availability. +Prior to the GA release of a major CockroachDB version, CockroachDB {{ site.data.products.cloud }} organizations can create new Dedicated clusters or upgrade existing clusters to a Pre-Production Preview release for testing and experimentation using a beta or release candidate (RC) of that next major version. Upgrading to a Pre-Production Preview is a major-version upgrade. After a cluster is upgraded to a Pre-Production Preview release, it is automatically upgraded to all subsequent releases within the same major version—including additional beta and RC releases, the GA release, and subsequent production patch releases as [patch version upgrades](#patch-version-upgrades). Upgrading to a Pre-Production Preview follows the same procedure as updating to a Production release. To learn more, refer to [Upgrade to {{ site.current_cloud_version }}]({% link cockroachcloud/upgrade-to-{{ site.current_cloud_version }}.md %}). -If you notice problems after a major version upgrade has been finalized, it will not be possible to roll back via the CockroachDB {{ site.data.products.cloud }} Console. For assistance, [contact support](https://support.cockroachlabs.com/hc/requests/new). +### Rollback support -### End of Support for CockroachDB versions +When upgrading a CockroachDB {{ site.data.products.dedicated }} cluster to a new major version, once all nodes are running the new version, the upgrade is finalized automatically in approximately 72 hours. During this window, if you see unexpected behavior, you can [trigger a rollback]({% link cockroachcloud/upgrade-to-{{ site.current_cloud_version }}.md %}#roll-back-the-upgrade) to the previous major version from the [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud). -As CockroachDB releases new major versions, older versions reach their End of Support (EOS) on CockroachDB {{ site.data.products.cloud }}. A CockroachDB version reaches EOS when it is two major versions behind the latest version. For example, when CockroachDB v21.2 was released, CockroachDB v20.2 reached EOS. +{{site.data.alerts.callout_info}} +If you choose to roll back a major version upgrade, your cluster will be rolled back to the latest patch release of the previous major version, which may differ from the patch release you were running before you initiated the upgrade. +{{site.data.alerts.end}} -Clusters running unsupported CockroachDB versions are not eligible for our [availability SLA](https://www.cockroachlabs.com/cloud-terms-and-conditions/). Further downgrades in support may occur as per the [CockroachDB Release Support Policy](https://www.cockroachlabs.com/docs/releases/release-support-policy). +During rollback, nodes are reverted one at a time to reduce the impact of the operation on the cluster's health and availability. -If you are running a CockroachDB version nearing EOS, you will be reminded at minimum one month before that version’s EOS that your clusters must be upgraded by the EOS date to avoid losing support. A Org Administrator can [upgrade your cluster]({% link cockroachcloud/upgrade-to-v23.2.md %}) directly from the CockroachDB {{ site.data.products.cloud }} Console. +If you notice problems after a major version upgrade has been finalized, it will not be possible to roll back via the CockroachDB {{ site.data.products.cloud }} Console. For assistance, [contact Support](https://support.cockroachlabs.com/hc/requests/new). ## Additional information -For more details about the upgrade and finalization process, see [Upgrade to the Latest CockroachDB Version](https://cockroachlabs.com/docs/cockroachcloud/upgrade-to-v23.1). +For more details about the upgrade and finalization process in CockroachDB, refer to the instructions on [upgrading to the latest CockroachDB version]({% link cockroachcloud/upgrade-to-{{site.current_cloud_version}}.md %}). diff --git a/src/current/cockroachcloud/upgrade-to-v23.2.md b/src/current/cockroachcloud/upgrade-to-v23.2.md index c12bf0aed67..e3f6e2dfa0f 100644 --- a/src/current/cockroachcloud/upgrade-to-v23.2.md +++ b/src/current/cockroachcloud/upgrade-to-v23.2.md @@ -16,7 +16,7 @@ pre_production_preview_version: v23.2.0-rc.2 [CockroachDB {{ page.pre_production_preview_version }}](https://www.cockroachlabs.com/docs/releases/{{ page.page_version }}#{{ page.pre_production_preview_version | replace: ".","-"}}) is available to CockroachDB {{ site.data.products.dedicated }} clusters as an opt-in upgrade for testing and experimentation. {{site.data.alerts.callout_danger}} -[Testing releases]({% link releases/index.md %}#release-naming) are not qualified for production environments and not eligible for support or uptime SLA commitments. +[Testing releases]({% link releases/index.md %}#overview) are not qualified for production environments and not eligible for support or uptime SLA commitments. {{site.data.alerts.end}} An [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) can upgrade your CockroachDB {{ site.data.products.dedicated }} cluster from the CockroachDB {{ site.data.products.cloud }} Console. This page guides you through the process of upgrading. diff --git a/src/current/cockroachcloud/upgrade-to-v24.1.md b/src/current/cockroachcloud/upgrade-to-v24.1.md index 9116975078c..306b8fb17ea 100644 --- a/src/current/cockroachcloud/upgrade-to-v24.1.md +++ b/src/current/cockroachcloud/upgrade-to-v24.1.md @@ -15,7 +15,8 @@ pre_production_preview_version: v24.1.0-rc.1 {% if page.pre_production_preview == true %} [CockroachDB {{ page.pre_production_preview_version }}](https://www.cockroachlabs.com/docs/releases/{{ page.page_version }}#{{ page.pre_production_preview_version | replace: ".","-"}}) is available to CockroachDB {{ site.data.products.dedicated }} clusters as an opt-in upgrade for testing and experimentation. -{{site.data.alerts.callout_danger}} [Testing releases]({% link releases/index.md %}#release-naming) are not qualified for production environments and not eligible for support or uptime SLA commitments. +{{site.data.alerts.callout_danger}} +[Testing releases]({% link releases/index.md %}#overview) are not qualified for production environments and not eligible for support or uptime SLA commitments. {{site.data.alerts.end}} An [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) can upgrade your CockroachDB {{ site.data.products.dedicated }} cluster from the CockroachDB {{ site.data.products.cloud }} Console. This page shows how to upgrade a CockroachDB {{ site.data.products.dedicated }} cluster to {{ page.pre_production_preview_version }} for testing and experimentation. diff --git a/src/current/cockroachcloud/upgrade-to-v24.2.md b/src/current/cockroachcloud/upgrade-to-v24.2.md new file mode 100644 index 00000000000..d8f3face32f --- /dev/null +++ b/src/current/cockroachcloud/upgrade-to-v24.2.md @@ -0,0 +1,169 @@ +--- +title: Upgrade to CockroachDB v24.2 +summary: Learn how to upgrade a cluster in CockroachDB Cloud to v24.2 +toc: true +docs_area: manage +page_version: v24.2 +prev_version: v24.1 +pre_production_preview: false +pre_production_preview_version: v24.1.0-rc.1 +--- + +{% capture previous_version_numeric %}{{ page.prev_version | remove_first: 'v' }}{% endcapture %} +{% capture major_version_numeric %}{{ page.page_version | remove_first: 'v' }}{% endcapture %} + +{% if page.pre_production_preview == true %} +[CockroachDB {{ page.pre_production_preview_version }}](https://www.cockroachlabs.com/docs/releases/{{ page.page_version }}#{{ page.pre_production_preview_version | replace: ".","-"}}) is available to CockroachDB {{ site.data.products.dedicated }} clusters as an opt-in upgrade for testing and experimentation. + +{{site.data.alerts.callout_danger}} +[Testing releases]({% link releases/index.md %}#overview) are not qualified for production environments and not eligible for support or uptime SLA commitments. +{{site.data.alerts.end}} + +An [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) can upgrade your CockroachDB {{ site.data.products.dedicated }} cluster from the CockroachDB {{ site.data.products.cloud }} Console. This page shows how to upgrade a CockroachDB {{ site.data.products.dedicated }} cluster to {{ page.pre_production_preview_version }} for testing and experimentation. + +{{site.data.alerts.callout_success}} +Upgrading from {{ page.prev_version }} to {{ page.pre_production_preview_version }} is a major-version upgrade. Upgrading a CockroachDB {{ site.data.products.dedicated }} cluster to a new major version is opt-in. Before proceeding, review the CockroachDB {{ site.data.products.cloud }} [CockroachDB Cloud Upgrade Policy](https://cockroachlabs.com/docs/cockroachcloud/upgrade-policy#pre-production-preview). After a cluster is upgraded to a Pre-Production Preview release, it is automatically upgraded to all subsequent releases within the same major version—including additional beta and RC releases, the GA release, and subsequent patch releases after GA, as patch version upgrades. To learn more, refer to [Patch Version Upgrades]({% link cockroachcloud/upgrade-policy.md %}#patch-version-upgrades). +{{site.data.alerts.end}} + +{% else %} +Now that [CockroachDB {{ page.page_version }}](https://www.cockroachlabs.com/docs/releases/ {{ page.page_version }}) is available, an [Org Administrator]({% link cockroachcloud/authorization.md %}#org-administrator) can upgrade your CockroachDB {{ site.data.products.dedicated }} cluster from the CockroachDB {{ site.data.products.cloud }} Console. This page shows how to upgrade a cluster in CockroachDB Cloud to {{ page.page_version }}. + +{{site.data.alerts.callout_success}} +Upgrading a CockroachDB {{ site.data.products.dedicated }} cluster to a new major version is opt-in. Before proceeding, review the CockroachDB {{ site.data.products.cloud }} [CockroachDB Cloud Upgrade Policy](https://cockroachlabs.com/docs/cockroachcloud/upgrade-policy). +{{site.data.alerts.end}} + +If you upgrade to a Pre-Production Preview of {{ page.page_version }}, your cluster will be automatically upgraded to {{ page.page_version }}.0 upon its GA release. +{% endif %} + +## Step 1. Verify that you can upgrade + +To upgrade to CockroachDB {{ page.page_version}}, you must be running {{ page.prev_version }}. If you are not running {{ page.prev_version }}, first [upgrade to {{ page.prev_version }}]({% link cockroachcloud/upgrade-to-{{ page.prev_version }}.md %}). Then return to this page and continue to [Step 2](#step-2-select-your-cluster-size). + +## Step 2. Select your cluster size + +The upgrade process depends on the number of nodes in your cluster. Select whether your cluster has multiple nodes or a single node: + +
+  +  +
+ +## Step 3. Understand the upgrade process + +
+In a multi-node cluster, the upgrade does not interrupt the cluster's overall health and availability. CockroachDB {{ site.data.products.cloud }} stops one node at a time and restarts it with the new version, waits a few minutes to observe the upgraded node's behavior, then moves on to the next node. This "rolling upgrade" takes approximately 4-5 minutes per node and is enabled by CockroachDB's [multi-active availability](https://www.cockroachlabs.com/docs/{{site.current_cloud_version}}/multi-active-availability) design. +
+ +
+When you start the upgrade, the cluster will be unavailable for a few minutes while the node is stopped and restarted with {{ page.page_version }}. +
+ +If you are upgrading from {{ page.prev_version }} to {{ page.page_version }}, the upgrade must be finalized. This is not required for subsequent patch upgrades. Approximately 72 hours after all nodes are running {{ page.page_version }}, the upgrade will be automatically [finalized]({% link {{ page.page_version }}/upgrade-cockroach-version.md %}#step-6-finish-the-upgrade). It's important to monitor your cluster and applications during this 72-hour window, so that you can [roll back the upgrade](#roll-back-the-upgrade) from the CockroachDB {{ site.data.products.cloud }} Console if you see [unexpected behavior according to key metrics]({% link {{ page.page_version }}/essential-metrics-dedicated.md %}) or if you experience application or database issues. Finalization enables certain [features and performance improvements introduced in {{ page.page_version }}](#expect-temporary-limitations). When finalization is complete, it is no longer possible to roll back to {{ page.prev_version }}. + +{{site.data.alerts.callout_info}} +If you choose to roll back a major version upgrade, your cluster will be rolled back to the latest patch release of {{ page.prev_version }}, which may differ from the patch release you were running before you initiated the upgrade. To learn more, refer to [CockroachDB Cloud Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). +{{site.data.alerts.end}} + +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](#expect-temporary-limitations). 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 CockroachDB {{ site.data.products.cloud }} [**Jobs** page]({% link cockroachcloud/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. + +Finalization is complete when all migration jobs have completed. After migration is complete, the command `SHOW CLUSTER SETTING version` will return `{{ major_version_numeric }}`. + +## Step 4. Prepare to upgrade + +Before starting the upgrade, complete the following steps. + +
+ +### Prepare for brief unavailability + +Your cluster will be unavailable while its single node is stopped and restarted with {{ page.page_version }}. Prepare your application for this brief downtime, typically a few minutes. + +The [**SQL Users**]({% link cockroachcloud/managing-access.md %}#create-a-sql-user) and [**Tools**]({% link cockroachcloud/tools-page.md %}) tabs in the CockroachDB {{ site.data.products.cloud }} Console will also be disabled during this time. + +
+ +### Review breaking changes + +{% comment %} Be careful with this logic and the page-level variable page_version {% endcomment %} +{% assign rd = site.data.versions | where_exp: "rd", "rd.major_version == page.page_version" | first %} + +{% if page.pre_production_preview == true %} +Review the backward-incompatible changes and deprecated features announced in each {{ page.page_version }} testing release. If any affect your applications, make the necessary changes before proceeding. +{% else %} +Review the backward-incompatible changes and deprecated features announced in the [{{ page.page_version }} release notes](https://www.cockroachlabs.com/docs/releases/{{ page.page_version }}) +{% endif %} + +## Step 5. Start the upgrade + +To start the upgrade process: + +1. [Sign in](https://cockroachlabs.cloud/) to your CockroachDB {{ site.data.products.cloud }} account. + +1. In the **Clusters** list, select the cluster you want to upgrade. + +1. Select **Actions > Upgrade {% if page.pre_production_preview == true %}to Pre-Production Preview{% else %}major version{% endif %}**. + +1. In the **Upgrade your cluster** dialog, review the pre-upgrade message and then click {% if page.pre_production_preview == true %}to Pre-Production Preview{% else %}major version{% endif %}. + +
+Your cluster will be upgraded one node at a time without interrupting the cluster's overall health and availability. This "rolling upgrade" will take approximately 4-5 minutes per node. +
+ +
+Your single-node cluster will be unavailable for a few minutes while the node is stopped and restarted with CockroachDB {{ page.page_version }}. +
+ +After it is started, an upgrade cannot be cancelled. Instead, you can wait for the upgrade to finish, then [roll it back](#roll-back-the-upgrade) for up to 72 hours, after which time it will be finalized and cannot be rolled back. + +## Step 6. Monitor the upgrade + +Once your cluster is running CockroachDB {{ page.page_version }}, you will have approximately 72 hours before the upgrade is automatically finalized. During this time, it is important to [monitor your applications](#monitor-your-application) and [expect temporary limitations](#expect-temporary-limitations). + +If you see unexpected behavior, you can [roll back](#roll-back-the-upgrade) to {{ page.prev_version }} during the 72-hour window. + +### Monitor your application + +Use the [DB Console]({% link cockroachcloud/tools-page.md %}) or your own tooling to monitor your application for any unexpected behavior. + +- If everything looks good, you can wait for the upgrade to automatically finalize or you can [manually trigger finalization](#finalize-the-upgrade). + +- If you see unexpected behavior, you can [roll back to the latest patch release of {{ page.prev_version }}](#roll-back-the-upgrade) during the 72-hour window. + +### Expect temporary limitations + +Most {{ page.page_version }} features can be used right away, but some will be enabled only after the upgrade has been finalized. Attempting to use these features before finalization will result in errors. + +For an expanded list of features included in {{ page.page_version }}, temporary limitations, backward-incompatible changes, and deprecated features, refer to the [{{ page.page_version }} release notes](https://www.cockroachlabs.com/docs/releases/{{ page.page_version }}). + +### Roll back the upgrade + +If you see unexpected behavior, you can roll back the upgrade during the 72-hour window. + +To stop the upgrade and roll back to {{ page.prev_version }}, click **Roll back** in the banner at the top of the CockroachDB {{ site.data.products.cloud }} Console, and then click **Roll back upgrade**. + +
+During rollback, nodes will be reverted to the latest production patch release of {{ page.prev_version }} one at a time without interrupting the cluster's health and availability. +
+ +
+Because your cluster contains a single node, the cluster will be briefly unavailable while the node is stopped and restarted with the latest production patch release of {{ page.prev_version }}. Be sure to [prepare for this brief unavailability](#prepare-for-brief-unavailability) before starting the rollback. +
+ +## Step 7. Complete the upgrade + +If everything looks good, you can wait for the upgrade to automatically finalize, or you can manually finalize the upgrade to lift the [temporary limitations](#expect-temporary-limitations) on the cluster more quickly. + +### Finalize the upgrade + +The upgrade is automatically finalized after 72 hours. + +To manually finalize the upgrade, click **Finalize** in the banner at the top of the CockroachDB {{ site.data.products.cloud }} Console, and then click **Finalize upgrade**. + +After finalization, all [temporary limitations](#expect-temporary-limitations) will be lifted and all {{ page.page_version }} features will be available for use. However, it will no longer be possible to roll back to {{ page.prev_version }}. If you see unexpected behavior after the upgrade has been finalized, [contact support](https://support.cockroachlabs.com/hc/requests/new). + +## See also + +- [CockroachDB Cloud Upgrade Policy](https://cockroachlabs.com/docs/cockroachcloud/upgrade-policy) +- [CockroachDB {{ page.page_version }} Release Notes](https://www.cockroachlabs.com/docs/releases/{{ page.page_version }}) diff --git a/src/current/releases/index.md b/src/current/releases/index.md index 7469e1194e5..e42da71766f 100644 --- a/src/current/releases/index.md +++ b/src/current/releases/index.md @@ -1,11 +1,8 @@ --- -title: Releases +title: CockroachDB Releases summary: Information about CockroachDB releases with an index of available releases and their release notes and binaries. toc: true docs_area: releases -toc_not_nested: true -pre_production_preview: true -pre_production_preview_version: v24.1.0-beta.1 --- {% comment %}Enable debug to print debug messages {% endcomment %} @@ -17,21 +14,119 @@ of this file, block-level HTML is indented in relation to the other HTML, and bl indented in relation to the other Liquid. Please try to keep the indentation consistent. Thank you! {% endcomment %} -After downloading a supported CockroachDB binary, learn how to [install CockroachDB](https://www.cockroachlabs.com/docs/stable/install-cockroachdb). Be sure to review Cockroach Labs' [Release Support Policy]({% link releases/release-support-policy.md %}). +{% assign all_production_releases = site.data.releases | where: "release_type", "Production" | sort: "release_date" | reverse %} +{% assign latest_full_production_version = all_production_releases | first %} -- **Generally Available (GA)** releases (also known as Production releases) are qualified for production environments. These may have either a default GA support type or an extended LTS (Long-Term Support) designation. Refer to [Release Support Policy]({% link releases/release-support-policy.md %}) for more information. -- **Testing** releases are intended for testing and experimentation only, and are not qualified for production environments and not eligible for support or uptime SLA commitments. Testing releases allow you to begin testing and validating the next major version of CockroachDB early. -- **Experimental** binaries allow you to deploy and develop with CockroachDB on architectures that are not yet qualified for production use. Experimental binaries are not eligible for support or uptime SLA commitments, whether they are for testing releases or production releases. +{% assign major_versions = all_production_releases | map: "major_version" | uniq | sort | reverse %} +{% assign latest_major_version_with_production = major_versions | first %} -For more details, refer to [Release Naming](#release-naming). For information about applicable software licenses, refer to [Licenses](#licenses). +## Overview + +A new major version of CockroachDB is released quarterly. After a series of testing releases, each major version receives an initial production release, follwed by a series of patch releases. + +Releases are named in the format `vYY.R.PP`, where `YY` indicates the year, `R` indicates the major release starting with `1` each year, and `PP` indicates the patch number, starting with `0`. + +For example, the latest production release is `{{ latest_full_production_version.release_name }}`, within major version [`{{ latest_major_version_with_production }}`]({% link releases/{{ latest_major_version_with_production }}.md %}). + +This page explains the types and naming of CockroachDB releases and provides access to the release notes and downloads for all CockroachDB [releases](#). + +After choosing a version of CockroachDB, learn how to: + +- [Create a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/create-a-serverless-cluster.md %}). +- [Upgrade a cluster in CockroachDB {{ site.data.products.cloud }}]({% link cockroachcloud/upgrade-to-{{site.current_cloud_version}}.md %}). +- [Install CockroachDB {{ site.data.products.core }}]({% link {{site.current_cloud_version}}/install-cockroachdb.md %}) +- [Upgrade a Self-Hosted cluster]({% link {{site.current_cloud_version}}/upgrade-cockroach-version.md %}). + +Be sure to review Cockroach Labs' [Release Support Policy]({% link releases/release-support-policy.md %}) and review information about applicable [software licenses](#licenses). + +### Release types + +#### Major releases + +As of 2024, every second major version is an **Innovation release**. For CockroachDB {{ site.data.products.core }} and CockroachDB {{ site.data.products.dedicated }}, these releases offer shorter support windows and can be skipped. + +All other major versions are **Regular releases**, which are required upgrades. These versions offer longer support periods, which, for self-hosted clusters, are further extended when a patch version is announced that begins their **LTS** (Long-Term Support) release series. + +For details on how this impacts support in CockroachDB {{ site.data.products.core }}, refer to [Release Support Policy]({% link releases/release-support-policy.md %}). For details on support per release type in CockroachDB Cloud, refer to [CockroachDB Cloud Support and Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). + +| Major Release Type | Frequency | Required upgrade | LTS releases and extended support | +| :---: | :---: | :---: | :---: | +| Regular (e.g. v24.1) | 2x/year | on Dedicated, Serverless, Self-Hosted | Yes | +| Innovation (e.g. v24.2) | 2x/year | on Serverless only | No* | +* Column does not apply to CockroachDB Serverless, where clusters are automatically upgraded when a new major version or a patch release is available, ensuring continuous support. + +For a given CockroachDB {{ site.data.products.core }} or Dedicated cluster, customers may choose to exclusively install or upgrade to Regular Releases to benefit from longer testing and support lifecycles, or to also include Innovation Releases, and benefit from earlier access to new features. This choice does not apply to CockroachDB Serverless, where every major release is an automatic upgrade. + +CockroachDB v24.2 is an Innovation release and v24.3 is planned as a Regular release. Starting with v25.1, four major releases are expected per year, where every first and third release of the year is expected to be an Innovation release. For more details, refer to [Upcoming releases](#upcoming-releases). + +#### Patch releases + +A major version has two types 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. + + + + + + + + + + + + + + + + + + + + + + + +
Patch Release TypeNamingDescription
ProductionvYY.R.0 - vYY.R.n
(ex. v24.2.1)		Production releases are qualified for production environments. The type and duration of support for a production release may vary depending on the major release type, according to the Release Support Policy.
TestingvYY.R.0-alpha.1+,
vYY.R.0-beta.1+,
vYY.R.0-rc.1+
(ex. v24.3.1-alpha.2)		Produced during development of a new major version, testing releases are intended for testing and experimentation only, and are not qualified for production environments or eligible for support or uptime SLA commitments.
{{site.data.alerts.callout_danger}} -In CockroachDB v22.2.x and above, a cluster that is upgraded to an alpha binary of CockroachDB or a binary that was manually built from the `master` branch cannot subsequently be upgraded to a production release. +A cluster that is upgraded to an alpha binary of CockroachDB or a binary that was manually built from the `master` branch cannot subsequently be upgraded to a production release. {{site.data.alerts.end}} -## Staged release process +### Staged release process + +As of 2024, CockroachDB is released under a staged delivery process. New releases are made available for select CockroachDB Cloud organizations for two weeks before binaries are published for CockroachDB {{ site.data.products.core }} downloads. + +### Recent releases + +{% comment %} TODO: Automate by Aug 12, 2024, or update the morning of August 12, then automate soon after. {% endcomment %} +| Version | Release Type | GA date | Latest patch release | +| :---: | :---: | :---: | :---: | +| [v24.2](#v24-2) | Innovation | 2024-08-12 | v24.2.0 | +| [v24.1](#v24-1) | Regular | 2024-05-20 | v24.1.3 | +| [v23.2](#v23-2) | Regular | 2024-02-05 | v23.2.9 (LTS) | +| [v23.1](#v23-1) | Regular | 2023-05-15 | v23.1.24 (LTS) | + +### Upcoming releases + +The following releases and their descriptions represent proposed plans that are subject to change. Please contact your account representative with any questions. + +| Version | Release Type | Expected GA date | +| :---: | :---: | :---: | +| v24.3 | Regular | 2024-11-18 | +| v25.1 | Innovation | 2025 Q1 | +| v25.2 | Regular | 2025 Q2 | +| v25.3 | Innovation | 2025 Q3 | +| v25.4 | Regular | 2025 Q4 | -As of 2024, CockroachDB is released under a staged delivery process. New releases are made available for select CockroachDB Cloud organizations for two weeks before binaries are published for CockroachDB Self-Hosted downloads. +## Downloads {{ experimental_js_warning }} @@ -66,8 +161,7 @@ As of 2024, CockroachDB is released under a staged delivery process. New release {% assign lts_patch = lts_patch_string | times: 1 %}{% comment %}Cast string to integer {% endcomment %} {% endif %} - -## {{ v.major_version }} +### {{ v.major_version }} {% if DEBUG == true %} has_lts_releases: {{ has_lts_releases }}
@@ -79,6 +173,11 @@ As of 2024, CockroachDB is released under a staged delivery process. New release v.release_date: {{ v.release_date }}
v.initial_lts_release_date: {{ v.initial_lts_release_date }}
{% endif %} +{% if v.major_version == "v24.2" %} +CockroachDB v24.2 is an [Innovation release](#major-releases), which is optional for CockroachDB {{ site.data.products.dedicated }} and CockroachDB {{ site.data.products.core }} clusters. Refer to [Major release types](#major-releases) before installing or upgrading for release support details. To learn what’s new in this release, refer to [Feature Highlights](https://www.cockroachlabs.com/docs/releases/v24.2.html). +{% endif %} +{% comment %}TODO: Link above to 24.2 Feature Highlights{% endcomment %} +
@@ -111,14 +210,14 @@ As of 2024, CockroachDB is released under a staged delivery process. New release {% assign v_docker_arm = false %} {% for r in releases %} - {% if r.docker.docker_arm == true %} + {% if r.docker.docker_arm == true %} {% assign v_docker_arm = true %} {% break %} {% endif %} {% endfor %} {% if releases[0] %} -### {{ s }} Releases +#### {{ s }} Releases
@@ -434,22 +533,6 @@ macOS downloads are **experimental**. Experimental downloads are not yet qualifi {% endfor %} {% comment %}for s in sections {% endcomment %} {% endfor %} {% comment %}for v in versions{% endcomment %} -## Release naming - -Cockroach Labs uses a three-component calendar versioning scheme to name CockroachDB [releases](https://cockroachlabs.com/docs/releases/index#production-releases). The format is `YY.R.PP`, where `YY` indicates the year, `R` indicates the release (historically “1” or “2”, representing a typical biannual cycle), and `PP` indicates the patch release version. Example: Version 23.1.0 (abbreviated v23.1.0). Leading up to a new major version's initial GA (Generally Available) release, multiple testing builds are produced, moving from Alpha to Beta to Release Candidate. CockroachDB began using this versioning scheme with v19.1. - -A major release is typically produced twice a year indicating major enhancements to product functionality. A change in the `YY.R` component denotes a major release. - -Patch releases are produced during the [support period]({% link releases/release-support-policy.md %}) for a major version to roll out critical bug and security fixes. A change in the `PP` component denotes a patch release. - -During development of a major version of CockroachDB, releases are produced according to the following patterns. Alpha, Beta, and Release Candidate releases are testing releases intended for testing and experimentation only, and are not qualified for production environments and not eligible for support or uptime SLA commitments. - -- Alpha releases are the earliest testing releases leading up to a major version's initial GA (generally available) release, and have `alpha` in the version name. Example: `v23.1.0-alpha.1`. -- Beta releases are produced after the series of alpha releases leading up to a major version's initial GA release, and tend to be more stable and introduce fewer changes than alpha releases. They have `beta` in the version name. Example: `v23.1.0-beta.1`. -- Release candidates are produced after the series of beta releases and are nearly identical to what will become the initial generally available (GA) release. Release candidates have `rc` in the version name. Example: `v23.1.0-rc.1`. -- A major version's initial GA release is produced after the series of release candidates for a major version, and ends with `0`. Example: `v23.1.0`. GA releases are validated and suitable for production environments. -- Patch (maintenance) releases are produced after a major version's GA release, and are numbered sequentially. Example: `v23.1.13`. - ## Licenses Unless otherwise noted, all binaries available on this page are variously licensed under the Business Source License 1.1 (BSL), the CockroachDB Community License (CCL), and other licenses specified in the source code. To determine whether BSL or CCL applies to a CockroachDB feature, refer to the [Licensing FAQs](https://www.cockroachlabs.com/docs/stable/licensing-faqs) page under Feature Licensing. The default license for any feature that is not listed is the CCL. diff --git a/src/current/releases/release-support-policy.md b/src/current/releases/release-support-policy.md index e897b9b4229..9d3c9e58d2d 100644 --- a/src/current/releases/release-support-policy.md +++ b/src/current/releases/release-support-policy.md @@ -2,6 +2,7 @@ title: Release Support Policy summary: Learn about Cockroach Labs' policy for supporting major releases of CockroachDB. toc: true +toc_not_nested: true docs_area: releases --- @@ -9,45 +10,58 @@ docs_area: releases {% assign versions = site.data.versions | where_exp: "versions", "versions.release_date <= today" | sort: "release_date" | reverse %} {% comment %} Get all versions (e.g., v21.2) sorted in reverse chronological order. {% endcomment %} -This page explains Cockroach Labs' policy for supporting [production releases]({% link releases/index.md %}) of CockroachDB Self-Hosted. For clusters deployed in {{ site.data.products.cloud }}, refer to the [CockroachDB {{ site.data.products.cloud }} Support and Upgrade Policy](https://www.cockroachlabs.com/docs/cockroachcloud/upgrade-policy). +This page explains Cockroach Labs' policy for supporting [production releases]({% link releases/index.md %}) of CockroachDB {{ site.data.products.core }}. For clusters deployed in {{ site.data.products.cloud }}, refer to the [CockroachDB {{ site.data.products.cloud }} Support and Upgrade Policy]({% link cockroachcloud/upgrade-policy.md %}). -There are two support types: GA and LTS (Long-Term Support). Each patch release of CockroachDB is assigned one of these types. The default is GA, unless otherwise specified. - -Initially, a major release series has GA support. After the series demonstrates a continuously high level of stability and performance, new patch releases are designated as LTS releases, which provide extended support windows. Specifically, the distinction determines the time spans of a release’s support phases: Maintenance Support, Assistance Support, and EOL (End of Life). +There are two major release types: [Regular and Innovation releases]({% link releases/index.md %}#release-types). Each offers a unique set of Support Types, which define the durations for each [support phase](#support-phases). ## Support Phases -- **Maintenance Support**: Cockroach Labs will produce regular patch releases that include critical security fixes and resolutions to problems identified by users. - -- **Assistance Support**: Immediately follows the Maintenance Support period. During this period, the following guidelines apply: - - New enhancements will not be made to the major release. +- **Maintenance Support**: Begins for a CockroachDB major version upon its [GA release]({% link releases/index.md %}#patch-releases). During this phase: + - Cockroach Labs will produce regular patch releases that include critical security fixes and resolutions to problems identified by users. + - Cockroach Labs may backport non-breaking enhancements produced for newer major versions. + - Cockroach Labs may direct customers to workarounds or other fixes applicable to a reported case. + - Cockroach Labs may recommend that customers [upgrade](https://www.cockroachlabs.com/docs/stable/upgrade-cockroach-version) to a later version of the product to resolve or further troubleshoot an issue. +- **Assistance Support**: Immediately follows the Maintenance Support phase for Regular releases. Innovation releases do not have an Assistance Support phase. During this phase: + - Feature enhancements will no longer be made available to the major release. - Cockroach Labs will continue to add critical security fixes to the major release in the form of patch releases. - Patch releases for the purpose of resolving bugs or other errors may no longer be made to the major release. - Cockroach Labs may direct customers to workarounds or other fixes applicable to the reported case. - - Cockroach Labs may direct customers to [upgrade](https://www.cockroachlabs.com/docs/stable/upgrade-cockroach-version) to a later version of the product, to resolve or further troubleshoot an issue. - -- **End of Life (EOL)**: Following the assistance support period, Cockroach Labs will no longer provide any support for the release. + - Cockroach Labs may direct customers to [upgrade](https://www.cockroachlabs.com/docs/stable/upgrade-cockroach-version) to a later version of CockroachDB to resolve or further troubleshoot an issue. +- **End of Life (EOL)**: The day that a major version’s final support period ends is its EOL date. After a version reaches EOL, Cockroach Labs provides no further support for the release. + - A Regular release reaches EOL at the Assistance Support phase's end date. + - An Innovation releases reaches EOL at the Maintenance Support phase's end date. ## Support Types -* **GA Support**: The default support type for production releases, starting with the initial production release of a major version, followed by each subsequent patch release before LTS releases begin for that major version. - * **Maintenance support ends**: - * **365 days** **after** the day of the **first production release** of the major version (i.e. the ‘GA release,’ ending in .0). - * **Assistance support ends**: - * **180 days after** the **Maintenance Support end date** of the release. - * Major versions prior to v23.1 will not have LTS releases. -* **LTS (Long-Term Support)**: Conferred to an initial LTS maintenance release of a given major version and its subsequent maintenance releases. LTS provides extended support windows while also indicating our highest level of expected release stability and performance. - * **Maintenance support ends**: - * **365 days** **after** the day of the **first LTS release** of the major version. - * **Assistance support ends**: - * **365 days after** the **Maintenance Support end date** of the release. +### Regular releases + +Initially, a Regular release series has GA Support. After the series demonstrates a continuously high level of stability and performance, new patch releases are designated as LTS releases, which have an extended support window for each [support phase](#support-phases): Maintenance Support, Assistance Support, and EOL (End of Life). -## Current supported releases +- **GA Support**: The default support type for production releases, starting with the initial production release of a major version, followed by each subsequent patch release before LTS releases begin for that major version. + - **Maintenance support ends**: + - **365 days** **after** the day of the **first production release** of the major version (i.e. the ‘GA release,’ ending in .0). + - **Assistance support ends**: + - **180 days after** the **Maintenance Support end date** of the release. + - Major versions prior to v23.1 will not have LTS releases. +- **LTS (Long-Term Support)**: Conferred to an initial LTS maintenance release of a given major version and its subsequent maintenance releases. LTS provides extended support windows while also indicating our highest level of expected release stability and performance. + - **Maintenance support ends**: + - **365 days** **after** the day of the **first LTS release** of the major version. + - **Assistance support ends**: + - **365 days after** the **Maintenance Support end date** of the release. -As of v19.1, Cockroach Labs uses a three-component calendar versioning scheme. Prior releases use a different versioning scheme. For more details, see [Release Naming]({% link releases/index.md %}#release-naming). +### Innovation releases -Date format: YYYY-MM-DD +Innovation releases do not have LTS releases. +- **Innovation Support**: + - **Maintenance Support ends:** + - **180 days after** the day of the **first production release** of the major version. + +Innovation releases are not eligible for Assistance Support, and reach EOL at the end of Maintenance Support. + +## Supported versions + +{% comment %}TODO: Bring in updated logic for Innovation{% endcomment %} @@ -120,10 +134,11 @@ Date format: YYYY-MM-DD
*  : This major version will receive LTS patch releases, which will be listed on an additional row, upon their availability.
+**  : This major version is an optional innovation release and will not receive LTS patch releases. Innovation releases are EOL when Maintenance Support ends.
-## End-of-life (EOL) releases +## End-of-life (EOL) versions -The following releases are no longer supported. +The following versions of CockroachDB are no longer supported. @@ -182,3 +197,5 @@ The following releases are no longer supported. {% endfor %} {% comment %} Display each EOL version, its release date, its maintenance support expiration date, and its assistance support expiration date, and its LTS maintenance and assistance support dates. Also include links to the latest hotfix version. {% endcomment %}
+ +**  : This EOL major version is an optional innovation release. Innovation releases do not receive LTS releases and are EOL when Maintenance Support ends.