Document patch deferral for CC and CCAPI #20871
Conversation
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
| 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}"}' |
There was a problem hiding this comment.
@nicholas-tao The example in the generated API docs includes deferred_until in the PUT request, which seems like an error: https://www.cockroachlabs.com/docs/api/cloud/v1#put-/api/v1/clusters/-cluster_id-/version-deferral
There was a problem hiding this comment.
yeah that doesn't seem right. can you please check with @VishalJaishankar to update the API docs?
| {{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. |
There was a problem hiding this comment.
What's the expected behavior when there are multiple patch upgrades deferred at once? e.g. x.10 releases and gets deferred for 90 days, then x.11 is released 25 days into the deferral window. Would a GET request to this endpoint return multiple deferred_until values? Or multiple objects?
There was a problem hiding this comment.
I read through the API code and believe it should only return one value based on the next immediate patch after the cluster's current version.
In your example where x.10 releases and is deferred for 90 days, then x.11 releases 25 days later:
- While cluster is on x.9: deferred_until = x.10 release date + 90 days
- After cluster upgrades to x.10: deferred_until = x.11 release date + 90 days
@VishalJaishankar is this correct?
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Left a couple comments and tagged @VishalJaishankar in some questions about the API behavior 😄
| 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}"}' |
There was a problem hiding this comment.
yeah that doesn't seem right. can you please check with @VishalJaishankar to update the API docs?
| {{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. |
There was a problem hiding this comment.
@VishalJaishankar are we planning to deprecate FIXED_DEFERRAL in favor of DEFERRAL_60_DAYS?
I know we kept it for backward compatibility reasons but if it's going to be deprecated, we should remove it from this line
| {{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. |
There was a problem hiding this comment.
I read through the API code and believe it should only return one value based on the next immediate patch after the cluster's current version.
In your example where x.10 releases and is deferred for 90 days, then x.11 releases 25 days later:
- While cluster is on x.9: deferred_until = x.10 release date + 90 days
- After cluster upgrades to x.10: deferred_until = x.11 release date + 90 days
@VishalJaishankar is this correct?
2 participants
https://cockroachlabs.atlassian.net/browse/DOC-13043
https://cockroachlabs.atlassian.net/browse/DOC-13042