Document patch deferral for CC and CCAPI

src/current/cockroachcloud/advanced-cluster-management.md

@@ -142,17 +142,19 @@ 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.
 1. From the **Start of window** dropdown, select a start time for your maintenance window in UTC.
 
     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 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).
 
 ## Restore data from a backup
 

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 `<sql_username>` 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.
+
+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
+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"
+}
+~~~
+
+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
+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 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.
+
+{{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 `"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"
+}
+~~~