ccloud CLI: Document new commands from SDK v6 update (ccloud-private#122)#22950
ccloud CLI: Document new commands from SDK v6 update (ccloud-private#122)#22950jordanlewis wants to merge 8 commits intomainfrom
Conversation
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
Files changed:
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
fantapop
left a comment
fantapop
left a comment
There was a problem hiding this comment.
Okay, I made it through the whole thing. There are some docs specific comments and some ccloud cli specific comments. I'm fine taking the ccloud ones as later improvements to the CLI.
| ~~~ | ||
|
|
||
| ~~~ | ||
| ∙∙∙ Retrieving cluster info... |
There was a problem hiding this comment.
One initial observation here and I'll let @jhlodin weigh in on the importance of this is that with the addition of all these new commands, this page is too long. It's supposed to be a "getting started" page.
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| ccloud cluster database list blue-dog |
There was a problem hiding this comment.
This looks slightly confusing but I guess it's right... After first I didn't realize blue-dog was the cluster name.
|
|
||
| ~~~ | ||
| ∙∙∙ Creating database... | ||
| Successfully created database 'myapp' | ||
| ~~~ |
There was a problem hiding this comment.
Not necessarily a change we need to make now but if we need to reduce the amount of content in this page, It seems like we could leave out stuff like this. (i.e. the output). I could see having dedicated pages for each command group and then linking to those.
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| ccloud cluster restore create blue-dog --source-cluster-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
There was a problem hiding this comment.
@jordanlewis usability nit that we allow passing the name for one of the clusters but require the id for the other. We can tackle it after the automation updates. https://cockroachlabs.atlassian.net/browse/CNSL-1926
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| ccloud cluster blackout-window create blue-dog --start 2026-04-01T00:00:00Z --end 2026-04-07T00:00:00Z |
There was a problem hiding this comment.
@jordanlewis it's definitely handy to accept the format with the T in it. But then the output is in a different format (without the T). Maybe we should use the T in the output...
| Status: ENABLING | ||
| ~~~ | ||
|
|
||
| To get the current Datadog configuration: |
There was a problem hiding this comment.
nit:
| To get the current Datadog configuration: | |
| To get the current Datadog metric export configuration: |
|
|
||
| ## Manage egress rules using `ccloud cluster networking egress-rule` | ||
|
|
||
| Use the `ccloud cluster networking egress-rule` commands to manage egress traffic rules for a CockroachDB {{ site.data.products.advanced }} cluster. Egress rules control which external destinations your cluster can connect to. |
There was a problem hiding this comment.
If there are appropriate areas of the docs that describe these features it would be great to cross link them
| f2a3b4c5-d6e7-8901-2345-678901abcdef Production FOLDER | ||
| a3b4c5d6-e7f8-9012-3456-789012abcdef Staging /Production FOLDER |
There was a problem hiding this comment.
This example is weird. The full path of the staging folder is /Production/Staging/
| ∙∙∙ Retrieving folder contents... | ||
| ID NAME TYPE PARENT PATH | ||
| 041d4c6b-69b9-4121-9c5a-8dd6ffd6b73d my-cluster CLUSTER /Production | ||
| a3b4c5d6-e7f8-9012-3456-789012abcdef Staging FOLDER /Production |
There was a problem hiding this comment.
again with the /Production/Staging/ folder
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| ccloud service-account api-key create b4c5d6e7-f8a9-0123-4567-890123abcdef deploy-key |
There was a problem hiding this comment.
I wonder if it's obvious enough that b4c5d6e7-f8a9-0123-4567-890123abcdef is the service account id? It's shown right above so maybe?
Documents all new command groups added in cockroachlabs/ccloud-private#122, which updated the ccloud CLI from SDK v3 to v6 and added comprehensive support for new Cloud API features. New command groups documented: - ccloud cluster connection-string - ccloud cluster database (list/create/delete) - ccloud cluster backup (list/config get/config update) - ccloud cluster restore (list/create) - ccloud cluster versions - ccloud cluster version-deferral (get/set) - ccloud cluster blackout-window (list/create/delete) - ccloud cluster maintenance (get/set/delete) - ccloud cluster disruption (get/set/clear) - ccloud cluster cmek get - ccloud cluster log-export (get/enable/disable) - ccloud cluster metric-export (cloudwatch/datadog/prometheus) - ccloud cluster networking egress-rule (list/create/delete) - ccloud cluster networking egress-private-endpoint (list/get/create/delete) - ccloud cluster networking client-ca-cert (get/set/update/delete) - ccloud cluster networking private-endpoint (services/connections/etc.) - ccloud organization get - ccloud audit list - ccloud billing invoice (list/get) - ccloud folder (list/get/create/update/delete/contents) - ccloud service-account (list/get/create/delete + api-key management) - ccloud jwt-issuer (list/get/create/update/delete) - ccloud replication (list/get/create/update)
- backup config update: --frequency-minutes/--retention-days → --frequency/--retention - restore create: backup ID is --backup-id flag, not positional arg; add --source-cluster-id and --type - version-deferral set: policy is --policy flag, not positional; list valid values - maintenance set: add required --duration flag, document --offset alternative, fix output format - disruption: rewrite section - it's disruption simulation, not "disruption budget" - log-export enable: --log-group → --log-name; fix output format - egress-rule create: remove nonexistent --ports flag; add --description - egress-private-endpoint create: --name/--service-name → --region/--target-service-identifier/--target-service-type - private-endpoint: fix command names (services → service list, add-connection → connection add, etc.) - private-endpoint: add missing trusted-owner subcommand group (list/add/remove) - replication create: --source-cluster/--target-cluster → --primary-cluster/--standby-cluster - replication update: --cutover → --status FAILING_OVER; add --failover-at - replication list: add required cluster name argument - folder list: PARENT ID → PARENT PATH, add TYPE column - Fix output table columns across multiple commands to match actual CLI output Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Verified all new command documentation against the actual ccloud codebase (testdata files and source code) and corrected: - Output formats: backup config/versions/version-deferral/cmek/client-ca-cert/ org get all use key-value format, not tables - Column names: backup list (AS OF TIME), versions (RELEASE TYPE/SUPPORT STATUS/SUPPORT END/ALLOWED UPGRADES), billing (STATUS/TOTAL), folder contents (ID/NAME/TYPE/PARENT PATH), service-account list (no CREATOR) - Status values: restore (SUCCESS/PENDING), egress-private-endpoint (AVAILABLE/PENDING), replication create (STARTING) - Positional args vs flags: folder create, service-account create, api-key create all take name as positional arg not --name flag; api-key list uses --service-account-id flag; api-key delete takes 1 arg not 2 - Connection string output includes Connection String header and Parameters section - Prometheus uses "metric scrape endpoint" not "metric export" - Various output message formatting (Successfully vs Success!, casing) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- CloudWatch/Datadog/Prometheus enable: add missing Cluster and Status lines to match source code output - Prometheus enable: revert incorrect "scrape endpoint" wording back to "metric export" to match source - Datadog enable: fix --site flag value to uppercase (US5) to match expected enum values - client-ca-cert set/update: fix "Success!" prefix to "Successfully" and add Status line to match source Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
jhlodin
force-pushed
the
jl/ccloud-cli-new-commands-docs
branch
from
8bf5c03 to
7bc8c15
Compare
|
Pushed a commit that refactors this content into two pages, one to retain the "get started" content for installation and connecting to a Cloud org, the rest that splits out all of the ccloud tasks into separate sections like what we have for the CCAPI https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api |
jhlodin
left a comment
jhlodin
left a comment
There was a problem hiding this comment.
Pushed my own commit to refactor this PR, tagging in another writer to give this a proper peer review
jhlodin
force-pushed
the
jl/ccloud-cli-new-commands-docs
branch
from
6324f11 to
c05190e
Compare
taroface
left a comment
taroface
left a comment
There was a problem hiding this comment.
Just adding a few initial comments -- I'll let another team member do a full review.
| ccloud cluster create serverless blue-dog us-central1 --cloud GCP --spend-limit 0 | ||
| ~~~ | ||
|
|
||
| ### Create a {{ site.data.products.advanced }} cluster |
There was a problem hiding this comment.
| ### Create a {{ site.data.products.advanced }} cluster | |
| ### Create an {{ site.data.products.advanced }} cluster |
|
|
||
| This command creates a 1-node CockroachDB {{ site.data.products.advanced }} cluster with 4 virtual CPUs (vCPUs) and 110 GiB of storage in the default cloud infrastructure provider (GCP) and the closest region for that provider. It will generate a cluster name. The CockroachDB version will be the latest stable version. | ||
|
|
||
| You can set the cluster name, cloud infrastructure provider, region, number of nodes, and storage as command options. The following command is equivalent to the previous command that uses the default values. |
There was a problem hiding this comment.
Lines 83-88 seem like they should be at the bottom of this section, for consistency with the preceding cmds
| regions: us-central1 | ||
| ~~~ | ||
|
|
||
| Showing cluster info for a {{ site.data.products.advanced }} cluster: |
There was a problem hiding this comment.
I suggest find-replacing more instances of this
| Showing cluster info for a {{ site.data.products.advanced }} cluster: | |
| Showing cluster info for an {{ site.data.products.advanced }} cluster: |
There was a problem hiding this comment.
Or replacing with a CockroachDB {{ site.data.products.advanced }}
| # Client version: CockroachDB CCL v21.2.5 (x86_64-apple-darwin19, built 2022/02/07 21:04:05, go1.16.6) | ||
| # Server version: CockroachDB CCL v21.2.4-1-g70835279ac (x86_64-unknown-linux-gnu, built 2022/02/03 22:31:25, go1.16.6) | ||
|
|
||
| warning: server version older than client! proceed with caution; some features may not be available. |
There was a problem hiding this comment.
Do we want this warning in here? Seems odd to have in the canonical example output
| ccloud cluster sql blue-dog --sso | ||
| ~~~ | ||
|
|
||
| {{site.data.alerts.callout_info}} |
There was a problem hiding this comment.
I don't love that this whole set of steps is inside a callout, but not sure if there is an obvious alternative
|
|
||
| The `ccloud cluster create` command creates a new CockroachDB {{ site.data.products.cloud }} cluster in your organization with the desired plan. | ||
|
|
||
| ### Create a {{ site.data.products.basic }} cluster |
There was a problem hiding this comment.
The current version of this doc has the variations of this command in filter tabs, which I find friendlier than stacking the three subcommands directly. Would suggest doing that here, unless we are trying to avoid the tabs due to the upcoming docs migration.
|
|
||
| ## Get information about a cluster | ||
|
|
||
| Use the `ccloud cluster info` command with the cluster name as the parameter to show detailed information about your cluster. Find the **Name** column in the output of `ccloud cluster list` to find the name of the cluster. |
There was a problem hiding this comment.
I'd link ccloud cluster list to its corresponding heading. Same goes for any other commands being referenced from another command.
4 participants
Summary
Documents all new command groups added in cockroachlabs/ccloud-private#122, which updated the
ccloudCLI from SDK v3 to v6 and added comprehensive support for new Cloud API features.New commands documented
Cluster commands
ccloud cluster connection-stringccloud cluster databaselist,create,deleteccloud cluster backuplist,config get,config updateccloud cluster restorelist,createccloud cluster versionsccloud cluster version-deferralget,setccloud cluster blackout-windowlist,create,deleteccloud cluster maintenanceget,set,deleteccloud cluster disruptionget,set,clearccloud cluster cmekgetccloud cluster log-exportget,enable,disableccloud cluster metric-exportcloudwatch,datadog,prometheus(each:get/enable/disable)ccloud cluster networking egress-rulelist,create,deleteccloud cluster networking egress-private-endpointlist,get,create,deleteccloud cluster networking client-ca-certget,set,update,deleteccloud cluster networking private-endpointservices,create-services,connections,add-connection,delete-connectionTop-level commands
ccloud organization getccloud audit listccloud billing invoicelist,getccloud folderlist,get,create,update,delete,contentsccloud service-accountlist,get,create,delete+api-keysubcommandsccloud jwt-issuerlist,get,create,update,deleteccloud replicationlist,get,create,updateNotes
filter-contentsection pattern{% include_cached copy-clipboard.html %}before code blocks,~~~ shellfor commands,~~~for output