Skip to content

Commit e3238e5

Browse files
jhlodinjhlodin
committed
Document patch deferral for CC and CCAPI
1 parent 90d91b5 commit e3238e5

File tree

2 files changed

+97
-3
lines changed

2 files changed

+97
-3
lines changed

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

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -142,17 +142,19 @@ Setting maintenance windows requires the [Cluster Admin]({% link cockroachcloud/
142142
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.
143143
{{site.data.alerts.end}}
144144

145-
To set a maintenance window:
145+
To set a maintenance window in the {{ site.data.products.cloud }} console:
146146

147147
1. Click the pencil icon next to **Cluster maintenance** to edit the maintenance window.
148148
1. From the **Day** dropdown, select the day of the week during which maintenance may be applied.
149149
1. From the **Start of window** dropdown, select a start time for your maintenance window in UTC.
150150

151151
The window will last for 6 hours from the start time.
152152

153-
1. (Optional) If you want to delay automatic patch upgrades for 60 days, switch **Delay patch upgrades** to **On**.
153+
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.
154154

155-
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.
155+
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.
156+
157+
You can also configure maintenance windows and patch upgrade deferral periods using the {{ site.data.products.cloud }} API.
156158

157159
## Restore data from a backup
158160

‎src/current/cockroachcloud/cloud-api.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1021,3 +1021,95 @@ If the request is successful, the client receives a response with the name of th
10211021
~~~
10221022

10231023
Where `<sql_username>` is the name of the SQL user whose password was changed.
1024+
1025+
## Configure a CockroachDB Advanced cluster's maintenance window
1026+
1027+
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.
1028+
1029+
{{site.data.alerts.callout_success}}
1030+
The service account associated with the secret key must have the Cluster Admin or Cluster Operator [role]({% link cockroachcloud/authorization.md %}#organization-user-roles).
1031+
{{site.data.alerts.end}}
1032+
1033+
{% include_cached copy-clipboard.html %}
1034+
~~~ shell
1035+
curl --request PUT \
1036+
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \
1037+
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
1038+
--json '{"offset_duration":"{offset_duration}","window_duration":"{window_duration}"}'
1039+
~~~
1040+
1041+
Where:
1042+
1043+
- `{cluster_id}` is the unique ID of this cluster.
1044+
{{site.data.alerts.callout_info}}
1045+
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 %}).
1046+
{{site.data.alerts.end}}
1047+
- `{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.
1048+
- `{window_duration}` is the length of the maintenance window, which must be greater than 6 hours and less than one week.
1049+
1050+
A cluster's existing maintenance window can be viewed with a `GET` request to the `/api/v1/clusters/{cluster_id}/maintenance-window` endpoint:
1051+
1052+
{% include_cached copy-clipboard.html %}
1053+
~~~ shell
1054+
curl --request GET \
1055+
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \
1056+
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
1057+
~~~
1058+
1059+
~~~ json
1060+
{
1061+
"offset_duration": "172800s",
1062+
"window_duration": "21600s"
1063+
}
1064+
~~~
1065+
1066+
A cluster's maintenance window can be removed with a `DELETE` request to the `/api/v1/clusters/{cluster_id}/maintenance-window` endpoint:
1067+
1068+
{% include_cached copy-clipboard.html %}
1069+
~~~ shell
1070+
curl --request DELETE \
1071+
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \
1072+
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
1073+
~~~
1074+
1075+
~~~ json
1076+
{
1077+
"offset_duration": "172800s",
1078+
"window_duration": "21600s"
1079+
}
1080+
~~~
1081+
1082+
### Set a patch upgrade deferral policy
1083+
1084+
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.
1085+
1086+
To set a patch upgrade deferral policy, send a `PUT` request to the `/api/v1/clusters/{cluster_id}/version-deferral` endpoint.
1087+
1088+
{{site.data.alerts.callout_success}}
1089+
The service account associated with the secret key must have the Cluster Admin or Cluster Operator [role]({% link cockroachcloud/authorization.md %}#organization-user-roles).
1090+
{{site.data.alerts.end}}
1091+
1092+
{% include_cached copy-clipboard.html %}
1093+
~~~ shell
1094+
curl --request PUT \
1095+
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/version-deferral \
1096+
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
1097+
--json '{"deferral_policy":"{deferral_policy}"}'
1098+
~~~
1099+
1100+
Where:
1101+
1102+
- `{cluster_id}` is the unique ID of this cluster.
1103+
{{site.data.alerts.callout_info}}
1104+
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 %}).
1105+
{{site.data.alerts.end}}
1106+
- `{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.
1107+
1108+
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.
1109+
1110+
{% include_cached copy-clipboard.html %}
1111+
~~~ shell
1112+
curl --request GET \
1113+
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/version-deferral \
1114+
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
1115+
~~~

0 commit comments

Comments
 (0)