From f0d81b859b3d156ee564712415719dd2702fa989 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Thu, 30 Oct 2025 13:07:09 -0400 Subject: [PATCH 1/4] Document patch deferral for CC and CCAPI --- .../advanced-cluster-management.md | 8 +- src/current/cockroachcloud/cloud-api.md | 99 +++++++++++++++++++ 2 files changed, 104 insertions(+), 3 deletions(-) diff --git a/src/current/cockroachcloud/advanced-cluster-management.md b/src/current/cockroachcloud/advanced-cluster-management.md index fe9b4d171d3..9067af29c3d 100644 --- a/src/current/cockroachcloud/advanced-cluster-management.md +++ b/src/current/cockroachcloud/advanced-cluster-management.md @@ -142,7 +142,7 @@ Setting maintenance windows requires the [Cluster Admin]({% link cockroachcloud/ Maintenance operations that are critical for cluster security or stability may be applied outside of the maintenance window, and upgrades that begin in a maintenance window may not always be completed by the end of the window. {{site.data.alerts.end}} -To set a maintenance window: +To set a maintenance window in the {{ site.data.products.cloud }} console: 1. Click the pencil icon next to **Cluster maintenance** to edit the maintenance window. 1. From the **Day** dropdown, select the day of the week during which maintenance may be applied. @@ -150,9 +150,11 @@ To set a maintenance window: The window will last for 6 hours from the start time. -1. (Optional) If you want to delay automatic patch upgrades for 60 days, switch **Delay patch upgrades** to **On**. +1. (Optional) If you want to delay automatic patch upgrades, switch **Delay patch upgrades** to **On**. You can set a deferral period of 30, 60, or 90 days after the patch is released. - Enable this setting for production clusters to ensure that development and testing clusters are upgraded before production clusters. This setting applies only to patch versions and not to other kinds of upgrades. + Enable this setting for production clusters to ensure that development and testing clusters are upgraded before production clusters. This setting applies only to patch versions and not to other kinds of upgrades. The patch upgrade occurs during a maintenance window after the deferral period. + +You can also configure maintenance windows and patch upgrade deferral periods using the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}#configure-a-cockroachdb-advanced-clusters-maintenance-window). ## Restore data from a backup diff --git a/src/current/cockroachcloud/cloud-api.md b/src/current/cockroachcloud/cloud-api.md index b8a67a83e8f..6a8e019d012 100644 --- a/src/current/cockroachcloud/cloud-api.md +++ b/src/current/cockroachcloud/cloud-api.md @@ -1021,3 +1021,102 @@ If the request is successful, the client receives a response with the name of th ~~~ Where `` is the name of the SQL user whose password was changed. + +## Configure a CockroachDB Advanced cluster's maintenance window + +To configure a [maintenance window]({% link cockroachcloud/advanced-cluster-management.md %}#set-a-maintenance-window) on a CockroachDB {{ site.data.products.advanced }} cluster, send a `PUT` request to the `/v1/clusters/{cluster_id}/maintenance-window` endpoint. + +{{site.data.alerts.callout_success}} +The service account associated with the secret key must have the Cluster Admin or Cluster Operator [role]({% link cockroachcloud/authorization.md %}#organization-user-roles). +{{site.data.alerts.end}} + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request PUT \ + --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \ + --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ + --json '{"offset_duration":"{offset_duration}","window_duration":"{window_duration}"}' +~~~ + +Where: + +- `{cluster_id}` is the unique ID of this cluster. +{{site.data.alerts.callout_info}} +The cluster ID used in the Cloud API is different from the routing ID used when [connecting to clusters]({% link cockroachcloud/connect-to-your-cluster.md %}). +{{site.data.alerts.end}} +- `{offset_duration}` is the start of the maintenance window, calculated as the amount of time after the start of a week (Monday 00:00 UTC) to begin the window. +- `{window_duration}` is the length of the maintenance window, which must be greater than 6 hours and less than one week. + +A cluster's existing maintenance window can be viewed with a `GET` request to the `/api/v1/clusters/{cluster_id}/maintenance-window` endpoint: + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request GET \ + --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \ + --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' +~~~ + +~~~ json +{ + "offset_duration": "172800s", + "window_duration": "21600s" +} +~~~ + +A cluster's maintenance window can be removed with a `DELETE` request to the `/api/v1/clusters/{cluster_id}/maintenance-window` endpoint: + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request DELETE \ + --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \ + --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' +~~~ + +~~~ json +{ + "offset_duration": "172800s", + "window_duration": "21600s" +} +~~~ + +### Set a patch upgrade deferral policy + +Automatic patch upgrades can be delayed for a period of 30, 60, or 90 days to ensure that development and testing clusters are upgraded before production clusters. This setting applies only to patch versions and not to other kinds of upgrades. + +To set a patch upgrade deferral policy, send a `PUT` request to the `/api/v1/clusters/{cluster_id}/version-deferral` endpoint. + +{{site.data.alerts.callout_success}} +The service account associated with the secret key must have the Cluster Admin or Cluster Operator [role]({% link cockroachcloud/authorization.md %}#organization-user-roles). +{{site.data.alerts.end}} + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request PUT \ + --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/version-deferral \ + --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ + --json '{"deferral_policy":"{deferral_policy}"}' +~~~ + +Where: + +- `{cluster_id}` is the unique ID of this cluster. +{{site.data.alerts.callout_info}} +The cluster ID used in the Cloud API is different from the routing ID used when [connecting to clusters]({% link cockroachcloud/connect-to-your-cluster.md %}). +{{site.data.alerts.end}} +- `{deferral_policy} is the length of the deferral window, set to `"DEFERRAL_30_DAYS"`, `"DEFERRAL_60_DAYS"`, or `"DEFERRAL_90_DAYS"`. Set to `"FIXED_DEFERRAL"` to defer upgrades by 60 days, or `"NOT_DEFERRED"` to remove the deferral policy and apply automatic patch upgrades immediately. + +To view the existing patch deferral policy and current patch upgrade deferrals, send a `GET` request to the `/api/v1/clusters/{cluster_id}/version-deferral` endpoint. + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request GET \ + --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/version-deferral \ + --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' +~~~ + +~~~ json +{ + "deferral_policy": "DEFERRAL_60_DAYS", + "deferred_until": "2025-12-15T00:00:00Z" +} +~~~ \ No newline at end of file From 61170092028461ddfff25b415feb08171d23eb47 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Tue, 4 Nov 2025 15:09:32 -0500 Subject: [PATCH 2/4] Remove deprecated value --- src/current/cockroachcloud/cloud-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/cockroachcloud/cloud-api.md b/src/current/cockroachcloud/cloud-api.md index 6a8e019d012..e4601416575 100644 --- a/src/current/cockroachcloud/cloud-api.md +++ b/src/current/cockroachcloud/cloud-api.md @@ -1103,7 +1103,7 @@ Where: {{site.data.alerts.callout_info}} The cluster ID used in the Cloud API is different from the routing ID used when [connecting to clusters]({% link cockroachcloud/connect-to-your-cluster.md %}). {{site.data.alerts.end}} -- `{deferral_policy} is the length of the deferral window, set to `"DEFERRAL_30_DAYS"`, `"DEFERRAL_60_DAYS"`, or `"DEFERRAL_90_DAYS"`. Set to `"FIXED_DEFERRAL"` to defer upgrades by 60 days, or `"NOT_DEFERRED"` to remove the deferral policy and apply automatic patch upgrades immediately. +- `{deferral_policy} is the length of the deferral window, set to `"DEFERRAL_30_DAYS"`, `"DEFERRAL_60_DAYS"`, or `"DEFERRAL_90_DAYS"`. Set to `"NOT_DEFERRED"` to remove the deferral policy and apply automatic patch upgrades immediately. To view the existing patch deferral policy and current patch upgrade deferrals, send a `GET` request to the `/api/v1/clusters/{cluster_id}/version-deferral` endpoint. From 914f65caa0a27775c5c68ee190c936b893d11d75 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Tue, 4 Nov 2025 15:42:37 -0500 Subject: [PATCH 3/4] Clarify 'other upgrades' meaning --- src/current/cockroachcloud/advanced-cluster-management.md | 2 +- src/current/cockroachcloud/cloud-api.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/current/cockroachcloud/advanced-cluster-management.md b/src/current/cockroachcloud/advanced-cluster-management.md index 9067af29c3d..40cb3b0841f 100644 --- a/src/current/cockroachcloud/advanced-cluster-management.md +++ b/src/current/cockroachcloud/advanced-cluster-management.md @@ -152,7 +152,7 @@ To set a maintenance window in the {{ site.data.products.cloud }} console: 1. (Optional) If you want to delay automatic patch upgrades, switch **Delay patch upgrades** to **On**. You can set a deferral period of 30, 60, or 90 days after the patch is released. - Enable this setting for production clusters to ensure that development and testing clusters are upgraded before production clusters. This setting applies only to patch versions and not to other kinds of upgrades. The patch upgrade occurs during a maintenance window after the deferral period. + Enable this setting for production clusters to ensure that development and testing clusters are upgraded before production clusters. This setting applies only to patch upgrades and not to major version upgrades. The patch upgrade occurs during a maintenance window after the deferral period. You can also configure maintenance windows and patch upgrade deferral periods using the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}#configure-a-cockroachdb-advanced-clusters-maintenance-window). diff --git a/src/current/cockroachcloud/cloud-api.md b/src/current/cockroachcloud/cloud-api.md index e4601416575..202c45ee0fe 100644 --- a/src/current/cockroachcloud/cloud-api.md +++ b/src/current/cockroachcloud/cloud-api.md @@ -1081,7 +1081,7 @@ curl --request DELETE \ ### Set a patch upgrade deferral policy -Automatic patch upgrades can be delayed for a period of 30, 60, or 90 days to ensure that development and testing clusters are upgraded before production clusters. This setting applies only to patch versions and not to other kinds of upgrades. +Automatic patch upgrades can be delayed for a period of 30, 60, or 90 days to ensure that development and testing clusters are upgraded before production clusters. This setting applies only to patch upgrades and not to major version upgrades. To set a patch upgrade deferral policy, send a `PUT` request to the `/api/v1/clusters/{cluster_id}/version-deferral` endpoint. From 1983792a781b21ad057c56cbf920784704642e9d Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Tue, 4 Nov 2025 15:43:02 -0500 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Ryan Kuo <8740013+taroface@users.noreply.github.com> --- src/current/cockroachcloud/cloud-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/current/cockroachcloud/cloud-api.md b/src/current/cockroachcloud/cloud-api.md index 202c45ee0fe..8e82bee91d0 100644 --- a/src/current/cockroachcloud/cloud-api.md +++ b/src/current/cockroachcloud/cloud-api.md @@ -1047,7 +1047,7 @@ The cluster ID used in the Cloud API is different from the routing ID used when - `{offset_duration}` is the start of the maintenance window, calculated as the amount of time after the start of a week (Monday 00:00 UTC) to begin the window. - `{window_duration}` is the length of the maintenance window, which must be greater than 6 hours and less than one week. -A cluster's existing maintenance window can be viewed with a `GET` request to the `/api/v1/clusters/{cluster_id}/maintenance-window` endpoint: +To view a cluster's existing maintenance window, send a `GET` request to the `/api/v1/clusters/{cluster_id}/maintenance-window` endpoint: {% include_cached copy-clipboard.html %} ~~~ shell @@ -1063,7 +1063,7 @@ curl --request GET \ } ~~~ -A cluster's maintenance window can be removed with a `DELETE` request to the `/api/v1/clusters/{cluster_id}/maintenance-window` endpoint: +To remove a cluster's maintenance window, send a `DELETE` request to the `/api/v1/clusters/{cluster_id}/maintenance-window` endpoint: {% include_cached copy-clipboard.html %} ~~~ shell