CC API docs updates for new plans/spec #18931

mikeCRL · 2024-09-23T17:00:00Z

src/current/cockroachcloud/cloud-api.md

Key updates to match the latest spec and offer additional details:

Updated intro to
- refer to latest API 'version'
- add note about TF provider
- flag the need to update code for former Serverless clusters
Modified cluster creation example to use STANDARD instead of Serverless
Updated cluster creation payload to include plan, and usage_limits instead of spendLimit
Modified the response examples for cluster creation, getting a cluster, getting all clusters, to align on the json object return for a cluster per spec example (Standard example only) and define more fields
Split ## Set the maximum resource limits of a Serverless cluster section into two new ones:
- Change resource limits for a Basic cluster & Change provisioned vCPUs for a Standard cluster
- Updated the endpoint and payload for changing resource limits
Updated various references from "Serverless" to "Basic" or "Standard" throughout the document

Notes:

Without improved Basic coverage, there wasn't an obvious place for delete_protection, so I didn't add it yet - want to confirm with you all first.
There are areas where the doc has been inconsistent with coverage in the spec and it's unclear where that's intentional. Generally, I'd like to plan a follow up review and iteration.
See comment about additional iteration after reviews, and follow-up plans

src/current/v24.2/api-support-policy.md

Improved the markdown structure of table, for easier visibility and easier editing in the future.
This may still be hard to view for this diff, so here are my proposed changes just to a few entries in the Availability column, for each interface. I'd appreciate verification of these edits and any other suggestions you may have; e.g. whether to add any stability/versioning mentions on CC API or in the main api doc.
- Prometheus endpoint: Dedicated -> Standard+Advanced (maybe metrics export should be a different line item, or not count at all here, i.e. drop the Standard mention. CC @kevin-v-ngo )
- Cluster API: Dedicated -> Advanced
- DB Console: Dedicated -> Advanced
- Logging: Dedicated -> Standard+Advanced (similarly maybe Standard needs a separate row? CC @kevin-v-ngo)
- ccloud CLI: No change ('applies to CC')
- Cloud API: No change ('applies to CC')
- Cloud Console: No change ('applies to CC')

To do:

Replicate v24.2 changes in all supported versions

Closes DOC-8920 DOC-9735 DOC-9730

github-actions · 2024-09-23T17:00:21Z

Files changed:

netlify · 2024-09-23T17:06:24Z

✅ Netlify Preview

Name	Link
🔨 Latest commit	`23d1ba6`
🔍 Latest deploy log	https://app.netlify.com/sites/cockroachdb-docs/deploys/66f458232481bc0008b1e149
😎 Deploy Preview	https://deploy-preview-18931--cockroachdb-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

src/current/cockroachcloud/cloud-api.md

mdlinville · 2024-09-23T18:39:36Z

src/current/cockroachcloud/cloud-api.md

  "spec": {
    "serverless": {
      "regions": [
        "{region_name}"
      ],
-      "spendLimit": {spend_limit}
+      "usage_limits": {
+        "provisioned_virtual_cpus": "2"


Can you update this example to use 4 vCPUs? 2 isn't allowed on Azure and 4 is our lower limit recommendation for production. It needs an jupdate to the --data field in the curl command too.

@mdlinville I think you're confusing provisioned_virtual_cpus with the Dedicated Hardware config field num_virtual_cpus. It doesn't look like provisioned_virtual_cpus has any such restrictions. @andy-kimball are all positive values valid here?

mdlinville · 2024-09-23T19:53:30Z

src/current/cockroachcloud/cloud-api.md

@@ -669,16 +799,17 @@ The service account associated with the secret key must have the Cluster Adminis
 {% include_cached copy-clipboard.html %}
 ~~~ shell
 curl --request DELETE \
-  --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users/{sql_username}'' \
+  --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users/{sql_username}' \


Nit: Poor alignment. I'd align --url with --request.

Leaving for consistency with other examples for now

mdlinville · 2024-09-23T19:53:42Z

src/current/cockroachcloud/cloud-api.md

 {{site.data.alerts.end}}
 - `{sql_username}` is the username of the SQL user you want to delete.
+- `{secret_key}` is the secret key for the service account.

 If the request was successful, the client will receive a response with the name of the deleted user.



I don't think we need to show the output.

Refined like the others

src/current/cockroachcloud/cloud-api.md

src/current/v24.2/api-support-policy.md

src/current/cockroachcloud/cloud-api.md

mikeCRL · 2024-09-24T15:28:57Z

Thanks for the reviews. Working on this now.

Co-authored-by: Matt Linville (he/him) <[email protected]>

mikeCRL

About to push an update. I believe I've addressed or replied to all comments.

Major changes:

Split the cluster creation into 3 sections, one each for Basic, Standard, Advanced.
Removed a number of unneeded response objects and field definitions, often linking out to the spec for details.
Confirmed that updating config does in fact return the updated cluster object (existing docs were wrong).

Follow-up items to log in an issue and revisit:

Establish consistency in how we link out to the spec for more information for a given section.
Establish a way to use content like field definitions directly from the spec.
Include latest API version number automatically by using a remote_include and extracting it from the cloud manifest.json
Include the CC version header in all example calls
Use includes for repeated text
Consider changing field definitions that say “fieldname is” to “fieldname:” or some other consistent format.
Revisit use of { vs < for field name definitions.
Remove raw json tabs or just show formatted json in the curl request.
General reexamination of details about the API included vs. omitted here, and if omitted, whether they should be included or referenced by linking to the spec.

src/current/cockroachcloud/cloud-api.md

mikeCRL · 2024-09-25T03:16:45Z

src/current/cockroachcloud/cloud-api.md

@@ -408,7 +504,7 @@ 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-a-basic-cluster.md %}).
+  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 %}).


Saving this as a follow-up action

mikeCRL · 2024-09-25T03:23:05Z

src/current/cockroachcloud/cloud-api.md

@@ -501,54 +596,71 @@ If the request was successful, the client will receive a list of all clusters wi
 {


Swapped to a high level representation, instead, representing real output from my testing

{ "clusters": [ {<cluster_object1>}, {<cluster_object2>}, {<cluster_object3>} ], "pagination": null }

mikeCRL · 2024-09-25T03:23:44Z

src/current/cockroachcloud/cloud-api.md

  }
 }
 ~~~

 Where:

+  - `{cloud_provider}` is the name of the cloud infrastructure provider. Possible values are: `GCP`, `AWS`, `AZURE`.


Dropping these, but adding a follow up task to standardize field definition format

mikeCRL · 2024-09-25T03:28:45Z

src/current/cockroachcloud/cloud-api.md

@@ -658,9 +784,13 @@ If the request was successful, the client will receive a response with the name



Streamlining and fixing braces instead of removing for now

mikeCRL · 2024-09-25T03:29:52Z

src/current/cockroachcloud/cloud-api.md

@@ -669,16 +799,17 @@ The service account associated with the secret key must have the Cluster Adminis
 {% include_cached copy-clipboard.html %}
 ~~~ shell
 curl --request DELETE \
-  --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users/{sql_username}'' \
+  --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users/{sql_username}' \


Leaving for consistency with other examples for now

mikeCRL · 2024-09-25T03:31:46Z

src/current/cockroachcloud/cloud-api.md

 {{site.data.alerts.end}}
 - `{sql_username}` is the username of the SQL user you want to delete.
+- `{secret_key}` is the secret key for the service account.

 If the request was successful, the client will receive a response with the name of the deleted user.



Refined like the others

src/current/cockroachcloud/cloud-api.md

src/current/v24.2/api-support-policy.md

andy-kimball · 2024-09-25T12:57:55Z

src/current/cockroachcloud/cloud-api.md

@@ -142,7 +157,7 @@ For example, to create a new free Serverless cluster named "notorious-moose" usi
 curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header 'Authorization: Bearer {secret_key}' \
-  --data '{"name":"notorious-moose","provider":"GCP","spec":{"serverless":{"regions":["us-central1"],"spendLimit":0}}}'
+  --json '{"name":"basic-test","provider":"GCP","plan":"BASIC","spec":{"serverless":{"regions":["us-central1"],"usage_limits":{"storage_mib_limit":"5242880","request_unit_limit":"50000000"}}}}'


It's rare for users to need limits; I don't think we should show an example using them. Instead, just like before, we should show the "unlimited" case where there's no "usage_limits" section. This is what we were doing before, when setting spendLimit = 0; I don't think we should change that.

Sounds good. Done.

src/current/cockroachcloud/cloud-api.md

andy-kimball · 2024-09-25T13:02:30Z

src/current/cockroachcloud/cloud-api.md

+curl --request POST \
+  --url https://cockroachlabs.cloud/api/v1/clusters \
+  --header 'Authorization: Bearer {secret_key}' \
+  --json '{"name":"{cluster_name}","provider":"{cloud_provider}","plan":"ADVANCED","spec":{"dedicated":{"region_nodes":{"{region_name}":3},"hardware":{"machine_spec":{"machine_type":"{machine_type}"}},"cockroach_version":"{version}"}}}'


We should not be encouraging users to use machine_spec with Advanced. Instead, we should be pointing them towards num_virtual_cpus.

andy-kimball · 2024-09-25T13:04:03Z

src/current/cockroachcloud/cloud-api.md

-## Set the maximum resource limits of a Serverless cluster
+<section class="filter-content" markdown="1" data-scope="curl">
+
+{% include_cached copy-clipboard.html %}


This is the right place to show usage limits in use, rather than above.

andy-kimball · 2024-09-25T13:05:13Z

src/current/cockroachcloud/cloud-api.md

+
+For details about returned fields, refer to the [response example and schema](https://www.cockroachlabs.com/docs/api/cloud/v1.html#patch-/api/v1/clusters/-cluster_id-) in the API reference.
+
+## Change the number of provisioned vCPUs for a Standard cluster


This might be a good place to mention that the number of provisioned vCPUs can be increased any number of times, but can only be decreased up to 3 times per week.

Done. Thanks.

andy-kimball · 2024-09-25T13:06:45Z

src/current/releases/cloud.md

@@ -567,7 +567,7 @@ For an in-depth explanation of CockroachDB {{ site.data.products.serverless }} p

 <h3 id="2023-01-09-api-changes"> Cloud API changes </h3>

- The [create cluster]({% link cockroachcloud/cloud-api.md %}#create-a-new-cluster) request now exposes the `restrict-egress-traffic` boolean field to allow dedicated clusters to be created with a [deny-by-default egress traffic policy]({% link cockroachcloud/egress-perimeter-controls.md %}#use-a-deny-by-default-egress-traffic-policy). This field and the broader egress perimeter controls capability can be used only with [private dedicated clusters]({% link cockroachcloud/private-clusters.md %}), which require the `network-visibility` field to be set to `NETWORK_VISIBILITY_PRIVATE`.
+- The [create cluster]({% link cockroachcloud/cloud-api.md %}#create-a-cluster) request now exposes the `restrict-egress-traffic` boolean field to allow dedicated clusters to be created with a [deny-by-default egress traffic policy]({% link cockroachcloud/egress-perimeter-controls.md %}#use-a-deny-by-default-egress-traffic-policy). This field and the broader egress perimeter controls capability can be used only with [private dedicated clusters]({% link cockroachcloud/private-clusters.md %}), which require the `network-visibility` field to be set to `NETWORK_VISIBILITY_PRIVATE`.


dedicated => Advanced

There are many old plan mentions in that doc; we're leaving them as-is, at least for now. A new release note today will cover the name changes.

mikeCRL

@andy-kimball Updated per your review. Thank you. Would you please take a look at the changes in the latest commit? (I won't hold up merging for this if you're busy prior to today's launch.)

mikeCRL · 2024-09-25T14:58:09Z

src/current/cockroachcloud/cloud-api.md

@@ -142,7 +157,7 @@ For example, to create a new free Serverless cluster named "notorious-moose" usi
 curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header 'Authorization: Bearer {secret_key}' \
-  --data '{"name":"notorious-moose","provider":"GCP","spec":{"serverless":{"regions":["us-central1"],"spendLimit":0}}}'
+  --json '{"name":"basic-test","provider":"GCP","plan":"BASIC","spec":{"serverless":{"regions":["us-central1"],"usage_limits":{"storage_mib_limit":"5242880","request_unit_limit":"50000000"}}}}'


Sounds good. Done.

mikeCRL · 2024-09-25T15:13:54Z

src/current/cockroachcloud/cloud-api.md

+curl --request POST \
+  --url https://cockroachlabs.cloud/api/v1/clusters \
+  --header 'Authorization: Bearer {secret_key}' \
+  --json '{"name":"{cluster_name}","provider":"{cloud_provider}","plan":"ADVANCED","spec":{"dedicated":{"region_nodes":{"{region_name}":3},"hardware":{"machine_spec":{"machine_type":"{machine_type}"}},"cockroach_version":"{version}"}}}'


src/current/cockroachcloud/cloud-api.md

mikeCRL · 2024-09-25T15:14:40Z

src/current/cockroachcloud/cloud-api.md

@@ -305,7 +339,7 @@ Where:

  - `{cluster_id}` is the cluster ID returned after creating the 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-a-basic-cluster.md %}).
+  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 %}).


Removed all unnecessary 'copy' includes.

mikeCRL · 2024-09-25T15:15:00Z

src/current/cockroachcloud/cloud-api.md

-## Set the maximum resource limits of a Serverless cluster
+<section class="filter-content" markdown="1" data-scope="curl">
+
+{% include_cached copy-clipboard.html %}


src/current/cockroachcloud/cloud-api.md

mikeCRL · 2024-09-25T15:20:33Z

src/current/cockroachcloud/cloud-api.md

+
+For details about returned fields, refer to the [response example and schema](https://www.cockroachlabs.com/docs/api/cloud/v1.html#patch-/api/v1/clusters/-cluster_id-) in the API reference.
+
+## Change the number of provisioned vCPUs for a Standard cluster


Done. Thanks.

mikeCRL · 2024-09-25T15:21:13Z

src/current/cockroachcloud/cloud-api.md

+To update the provisioned vCPUs for a cluster, send a `PATCH` request to the `/v1/clusters/{cluster_id}` endpoint.
+
+{{site.data.alerts.callout_success}}
+The service account associated with the secret key must have the Cluster Administrator or Cluster Developer [role]({% link cockroachcloud/authorization.md %}#organization-user-roles).


mikeCRL · 2024-09-25T15:21:26Z

src/current/cockroachcloud/cloud-api.md

+
+Where:
+
+  - `{cluster_id}` is the unique ID of this cluster.


saved as follow up task

mikeCRL · 2024-09-25T15:23:30Z

src/current/releases/cloud.md

@@ -567,7 +567,7 @@ For an in-depth explanation of CockroachDB {{ site.data.products.serverless }} p

 <h3 id="2023-01-09-api-changes"> Cloud API changes </h3>

- The [create cluster]({% link cockroachcloud/cloud-api.md %}#create-a-new-cluster) request now exposes the `restrict-egress-traffic` boolean field to allow dedicated clusters to be created with a [deny-by-default egress traffic policy]({% link cockroachcloud/egress-perimeter-controls.md %}#use-a-deny-by-default-egress-traffic-policy). This field and the broader egress perimeter controls capability can be used only with [private dedicated clusters]({% link cockroachcloud/private-clusters.md %}), which require the `network-visibility` field to be set to `NETWORK_VISIBILITY_PRIVATE`.
+- The [create cluster]({% link cockroachcloud/cloud-api.md %}#create-a-cluster) request now exposes the `restrict-egress-traffic` boolean field to allow dedicated clusters to be created with a [deny-by-default egress traffic policy]({% link cockroachcloud/egress-perimeter-controls.md %}#use-a-deny-by-default-egress-traffic-policy). This field and the broader egress perimeter controls capability can be used only with [private dedicated clusters]({% link cockroachcloud/private-clusters.md %}), which require the `network-visibility` field to be set to `NETWORK_VISIBILITY_PRIVATE`.


There are many old plan mentions in that doc; we're leaving them as-is, at least for now. A new release note today will cover the name changes.

netlify · 2024-09-25T18:36:47Z

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name	Link
🔨 Latest commit	`23d1ba6`
🔍 Latest deploy log	https://app.netlify.com/sites/cockroachdb-interactivetutorials-docs/deploys/66f45823248a480008b2f1e1

netlify · 2024-09-25T18:36:49Z

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name	Link
🔨 Latest commit	`23d1ba6`
🔍 Latest deploy log	https://app.netlify.com/sites/cockroachdb-api-docs/deploys/66f4582306f65d0008bae5cb

src/current/cockroachcloud/cloud-api.md

mikeCRL added 2 commits September 23, 2024 12:05

Update Cloud API docs for new version

d87a735

Update API Support Policy

dc27a02

mikeCRL changed the title ~~API updates for Cloud 2.0~~ API updates for new plans/spec Sep 23, 2024

mikeCRL changed the title ~~API updates for new plans/spec~~ CC API docs updates for new plans/spec Sep 23, 2024

mikeCRL marked this pull request as ready for review September 23, 2024 17:47

mikeCRL requested review from marksoper, fantapop, mdlinville and andy-kimball September 23, 2024 17:48

Fix DB console mention to drop Standard

1f804a3

mdlinville reviewed Sep 23, 2024

View reviewed changes

fantapop reviewed Sep 24, 2024

View reviewed changes

src/current/cockroachcloud/cloud-api.md Outdated Show resolved Hide resolved

Apply some suggestions from code review

e0236b6

Co-authored-by: Matt Linville (he/him) <[email protected]>

mikeCRL commented Sep 25, 2024

View reviewed changes

mikeCRL added 2 commits September 24, 2024 23:50

Various updates inspired by review

5bb12d1

Anchor link fixes and minor tweaks

b2b33e2

mikeCRL requested review from fantapop and mdlinville September 25, 2024 04:25

Add link to provisioned capacity docs

a2f0beb

mdlinville approved these changes Sep 25, 2024

View reviewed changes

andy-kimball reviewed Sep 25, 2024

View reviewed changes

Updates per review feedback

98af4e2

mikeCRL commented Sep 25, 2024

View reviewed changes

Base automatically changed from cloud-2.0 to main September 25, 2024 18:21

Merge branch 'main' into api-updates-cloud-2.0

23d1ba6

mikeCRL merged commit 8f2d690 into main Sep 25, 2024
6 checks passed

mikeCRL deleted the api-updates-cloud-2.0 branch September 25, 2024 18:53

andy-kimball reviewed Sep 25, 2024

View reviewed changes

src/current/cockroachcloud/cloud-api.md Show resolved Hide resolved

mikeCRL mentioned this pull request Sep 26, 2024

Fix Advanced API call #18951

Merged

		@@ -501,54 +596,71 @@ If the request was successful, the client will receive a list of all clusters wi
		{

		@@ -658,9 +784,13 @@ If the request was successful, the client will receive a response with the name


		For details about returned fields, refer to the [response example and schema](https://www.cockroachlabs.com/docs/api/cloud/v1.html#patch-/api/v1/clusters/-cluster_id-) in the API reference.

		## Change the number of provisioned vCPUs for a Standard cluster

CC API docs updates for new plans/spec #18931

CC API docs updates for new plans/spec #18931

Conversation

mikeCRL commented Sep 23, 2024 • edited Loading

github-actions bot commented Sep 23, 2024 • edited Loading

Files changed:

netlify bot commented Sep 23, 2024 • edited Loading

✅ Netlify Preview

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mikeCRL commented Sep 24, 2024

mikeCRL left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mikeCRL left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

netlify bot commented Sep 25, 2024

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

netlify bot commented Sep 25, 2024

✅ Deploy Preview for cockroachdb-api-docs canceled.

mikeCRL commented Sep 23, 2024 •

edited

Loading

github-actions bot commented Sep 23, 2024 •

edited

Loading

netlify bot commented Sep 23, 2024 •

edited

Loading

mikeCRL left a comment •

edited

Loading