From bb13aac269657176b70bc3024a2ef1b19134afd6 Mon Sep 17 00:00:00 2001 From: Jack Westwood Date: Wed, 9 Oct 2024 14:03:32 +0100 Subject: [PATCH] Add documentation for the clusters commands --- docs/commands.adoc | 2 + docs/commands/clusters.adoc | 240 ++++++++++++++++++++++++++++++++++++ 2 files changed, 242 insertions(+) create mode 100644 docs/commands/clusters.adoc diff --git a/docs/commands.adoc b/docs/commands.adoc index 5e4d4de7..85038b6d 100644 --- a/docs/commands.adoc +++ b/docs/commands.adoc @@ -5,6 +5,8 @@ them with built-in other shell commands as well as executable programs from your include::commands/buckets.adoc[] +include::commands/clusters.adoc[] + include::commands/columnar.adoc[] include::commands/scopes.adoc[] diff --git a/docs/commands/clusters.adoc b/docs/commands/clusters.adoc new file mode 100644 index 00000000..caa62018 --- /dev/null +++ b/docs/commands/clusters.adoc @@ -0,0 +1,240 @@ +=== clusters + +The `clusters` commands are used to perform management operations against Capella clusters. +In order to use these commands you will need to configure a Capella organization in the https://couchbase.sh/docs/#_the_config_dotfiles[config file]. + +==== `clusters` + +Lists all the Capella clusters in the active project/Organization. + +[options="nowrap"] +``` +👤 Charlie 🏠 remote in ☁️ default._default._default +> clusters +╭───┬────────────────────────────────────┬──────────────────────────────────────┬───────────────┬───────────────────────────╮ +│ # │ name │ id │ state │ cloud provider │ +├───┼────────────────────────────────────┼──────────────────────────────────────┼───────────────┼───────────────────────────┤ +│ 0 │ calmgeorgenovacky │ 88e66a4e-d166-43d5-9840-64ce14ac872f │ destroyFailed │ ╭────────┬──────────────╮ │ +│ │ │ │ │ │ type │ gcp │ │ +│ │ │ │ │ │ region │ us-east4 │ │ +│ │ │ │ │ │ cidr │ 10.0.15.0/24 │ │ +│ │ │ │ │ ╰────────┴──────────────╯ │ +│ 1 │ carefulalbertociaramella │ 701eac0c-e3a1-450d-b3ff-7f1edbdce830 │ healthy │ ╭────────┬──────────────╮ │ +│ │ │ │ │ │ type │ aws │ │ +│ │ │ │ │ │ region │ us-east-1 │ │ +│ │ │ │ │ │ cidr │ 10.0.19.0/24 │ │ +│ │ │ │ │ ╰────────┴──────────────╯ │ +│ 2 │ daringmarioszegedy │ 091fe3fa-0304-4574-87d1-e12ae8586dd1 │ healthy │ ╭────────┬──────────────╮ │ +│ │ │ │ │ │ type │ aws │ │ +│ │ │ │ │ │ region │ us-east-1 │ │ +│ │ │ │ │ │ cidr │ 10.0.20.0/24 │ │ +│ │ │ │ │ ╰────────┴──────────────╯ │ +│ 3 │ saicharan-politecharlesstarkdraper │ ca209e7d-4d39-4356-9a9e-decab12b20e4 │ healthy │ ╭────────┬──────────────╮ │ +│ │ │ │ │ │ type │ aws │ │ +│ │ │ │ │ │ region │ us-east-1 │ │ +│ │ │ │ │ │ cidr │ 10.0.17.0/24 │ │ +│ │ │ │ │ ╰────────┴──────────────╯ │ +╰───┴────────────────────────────────────┴──────────────────────────────────────┴───────────────┴───────────────────────────╯ +``` + +Check this https://couchbase.sh/docs/recipes/#_register_clusters[recipe] for how to register all the clusters in a project for use with the shell. + +==== `clusters create` + +Creates a cluster from either a full definition piped in or from values chosen using flags. +The minimum required is for the user to choose a cloud provider, this can be aws, gcp or azure: + +[options="nowrap"] +``` +👤 Charlie 🏠 remote in ☁️ default._default._default +> clusters create --provider aws +👤 Charlie 🏠 remote in ☁️ default._default._default +> clusters +╭───┬────────────────────────┬──────────────────────────────────────┬───────────┬───────────────────────────╮ +│ # │ name │ id │ state │ cloud provider │ +├───┼────────────────────────┼──────────────────────────────────────┼───────────┼───────────────────────────┤ +│ 0 │ cbshell-cluster-2cd8d6 │ 1e3b86a6-f039-479e-be60-12330af49e67 │ deploying │ ╭────────┬──────────────╮ │ +│ │ │ │ │ │ type │ aws │ │ +│ │ │ │ │ │ region │ us-east-1 │ │ +│ │ │ │ │ │ cidr │ 10.0.23.0/24 │ │ +│ │ │ │ │ ╰────────┴──────────────╯ │ +╰───┴────────────────────────┴──────────────────────────────────────┴───────────┴───────────────────────────╯ +``` + +This will create a single node cluster, running the index, data query and search services. +The full list of flags supported by `clusters create` is: + +``` + --name - the name of the cluster + --provider - the cloud provider + --version - the couchbase server version + --capella - the Capella organization to use + --nodes - the number of nodes in the cluster + --project - the Capella project to use +``` + +If you want complete control over the structure of the cluster then you can pipe a JSON cluster definition into the command: + +``` +👤 Charlie 🏠 remote in ☁️ default._default._default +> cat gcp-cluster-def.json +{ + "name": "GCP-CBShell", + "description": "A gcp cluster created using cbshell", + "cloudProvider": { + "type": "gcp", + "region": "us-east1" + }, + "serviceGroups": [ + { + "node": { + "compute": { + "cpu": 4, + "ram": 16 + }, + "disk": { + "storage": 64, + "type": "pd-ssd" + } + }, + "numOfNodes": 3, + "services": [ + "data", + "query", + "index", + "search" + ] + } + ], + "availability": { + "type": "multi" + }, + "support": { + "plan": "developer pro", + "timezone": "PT" + } +} +👤 Charlie 🏠 remote in ☁️ default._default._default +> cat gcp-cluster-def.json | clusters create +👤 Charlie 🏠 remote in ☁️ default._default._default +> clusters +╭───┬─────────────┬──────────────────────────────────────┬───────────┬───────────────────────────╮ +│ # │ name │ id │ state │ cloud provider │ +├───┼─────────────┼──────────────────────────────────────┼───────────┼───────────────────────────┤ +│ 0 │ GCP-CBShell │ c60b070f-6656-4e25-9b22-0cee497bea6a │ deploying │ ╭────────┬──────────────╮ │ +│ │ │ │ │ │ type │ gcp │ │ +│ │ │ │ │ │ region │ us-east1 │ │ +│ │ │ │ │ │ cidr │ 10.0.23.0/24 │ │ +│ │ │ │ │ ╰────────┴──────────────╯ │ +╰───┴─────────────┴──────────────────────────────────────┴───────────┴───────────────────────────╯ +``` + +See the https://docs.couchbase.com/cloud/management-api-reference/index.html?_gl=1*npyoqk*_gcl_au*MTYxNDg3MjgyMS4xNzI2MjMxMTMx#tag/Clusters/operation/postCluster[Capella API docs] for more examples of cluster definitions with different providers. + +==== `clusters drop` + +This deletes a cluster with the given name in the active project. + +``` +👤 Charlie 🏠 remote in ☁️ default._default._default +> clusters +╭───┬─────────────┬──────────────────────────────────────┬───────────┬───────────────────────────╮ +│ # │ name │ id │ state │ cloud provider │ +├───┼─────────────┼──────────────────────────────────────┼───────────┼───────────────────────────┤ +│ 0 │ GCP-CBShell │ c60b070f-6656-4e25-9b22-0cee497bea6a │ healthy │ ╭────────┬──────────────╮ │ +│ │ │ │ │ │ type │ gcp │ │ +│ │ │ │ │ │ region │ us-east1 │ │ +│ │ │ │ │ │ cidr │ 10.0.23.0/24 │ │ +│ │ │ │ │ ╰────────┴──────────────╯ │ +╰───┴─────────────┴──────────────────────────────────────┴───────────┴───────────────────────────╯ +👤 Charlie 🏠 remote in ☁️ default._default._default +> clusters drop GCP-CBShell +👤 Charlie 🏠 remote in ☁️ default._default._default +> clusters +╭────────────╮ +│ empty list │ +╰────────────╯ +``` + +==== `clusters get` + +Gets the full details of a named cluster. +Say we have the following clusters in our project: + +[options="nowrap"] +``` +👤 Charlie 🏠 remote in ☁️ default._default._default +> clusters +╭───┬────────────────────────────────────┬──────────────────────────────────────┬───────────────┬───────────────────────────╮ +│ # │ name │ id │ state │ cloud provider │ +├───┼────────────────────────────────────┼──────────────────────────────────────┼───────────────┼───────────────────────────┤ +│ 0 │ calmgeorgenovacky │ 88e66a4e-d166-43d5-9840-64ce14ac872f │ destroyFailed │ ╭────────┬──────────────╮ │ +│ │ │ │ │ │ type │ gcp │ │ +│ │ │ │ │ │ region │ us-east4 │ │ +│ │ │ │ │ │ cidr │ 10.0.15.0/24 │ │ +│ │ │ │ │ ╰────────┴──────────────╯ │ +│ 1 │ carefulalbertociaramella │ 701eac0c-e3a1-450d-b3ff-7f1edbdce830 │ healthy │ ╭────────┬──────────────╮ │ +│ │ │ │ │ │ type │ aws │ │ +│ │ │ │ │ │ region │ us-east-1 │ │ +│ │ │ │ │ │ cidr │ 10.0.19.0/24 │ │ +│ │ │ │ │ ╰────────┴──────────────╯ │ +│ 2 │ daringmarioszegedy │ 091fe3fa-0304-4574-87d1-e12ae8586dd1 │ healthy │ ╭────────┬──────────────╮ │ +│ │ │ │ │ │ type │ aws │ │ +│ │ │ │ │ │ region │ us-east-1 │ │ +│ │ │ │ │ │ cidr │ 10.0.20.0/24 │ │ +│ │ │ │ │ ╰────────┴──────────────╯ │ +│ 3 │ saicharan-politecharlesstarkdraper │ ca209e7d-4d39-4356-9a9e-decab12b20e4 │ healthy │ ╭────────┬──────────────╮ │ +│ │ │ │ │ │ type │ aws │ │ +│ │ │ │ │ │ region │ us-east-1 │ │ +│ │ │ │ │ │ cidr │ 10.0.17.0/24 │ │ +│ │ │ │ │ ╰────────┴──────────────╯ │ +╰───┴────────────────────────────────────┴──────────────────────────────────────┴───────────────┴───────────────────────────╯ +``` + +We can get the details about `carefulalbertociaramella`: + +``` +👤 Charlie 🏠 remote in ☁️ default._default._default +> clusters get carefulalbertociaramella +╭────────────────────┬───────────────────────────────────────────────────────────────────────╮ +│ name │ carefulalbertociaramella │ +│ id │ 701eac0c-e3a1-450d-b3ff-7f1edbdce830 │ +│ description │ │ +│ state │ healthy │ +│ connection string │ cb.ldznce3jxg5tav5u.cloud.couchbase.com │ +│ configuration type │ singleNode │ +│ │ ╭─────────┬───────╮ │ +│ server │ │ version │ 7.6.3 │ │ +│ │ ╰─────────┴───────╯ │ +│ │ ╭────────┬──────────────╮ │ +│ cloud provider │ │ type │ aws │ │ +│ │ │ region │ us-east-1 │ │ +│ │ │ cidr │ 10.0.19.0/24 │ │ +│ │ ╰────────┴──────────────╯ │ +│ │ ╭───┬──────────────────────────────────┬────────────┬───────────────╮ │ +│ service groups │ │ # │ node │ numOfNodes │ services │ │ +│ │ ├───┼──────────────────────────────────┼────────────┼───────────────┤ │ +│ │ │ 0 │ ╭─────────┬────────────────────╮ │ 1 │ ╭───┬───────╮ │ │ +│ │ │ │ │ │ ╭─────┬────╮ │ │ │ │ 0 │ index │ │ │ +│ │ │ │ │ compute │ │ cpu │ 4 │ │ │ │ │ 1 │ data │ │ │ +│ │ │ │ │ │ │ ram │ 16 │ │ │ │ │ 2 │ query │ │ │ +│ │ │ │ │ │ ╰─────┴────╯ │ │ │ ╰───┴───────╯ │ │ +│ │ │ │ │ │ ╭─────────┬──────╮ │ │ │ │ │ +│ │ │ │ │ disk │ │ type │ gp3 │ │ │ │ │ │ +│ │ │ │ │ │ │ storage │ 50 │ │ │ │ │ │ +│ │ │ │ │ │ │ iops │ 3000 │ │ │ │ │ │ +│ │ │ │ │ │ ╰─────────┴──────╯ │ │ │ │ │ +│ │ │ │ ╰─────────┴────────────────────╯ │ │ │ │ +│ │ ╰───┴──────────────────────────────────┴────────────┴───────────────╯ │ +│ │ ╭──────┬────────╮ │ +│ availability │ │ type │ single │ │ +│ │ ╰──────┴────────╯ │ +│ │ ╭──────────┬───────────────╮ │ +│ support │ │ plan │ developer pro │ │ +│ │ │ timezone │ PT │ │ +│ │ ╰──────────┴───────────────╯ │ +╰────────────────────┴───────────────────────────────────────────────────────────────────────╯ +``` + +One of the particularly useful fields returned by `clusters get` is the `connection string`. +Check this https://couchbase.sh/docs/recipes/#_register_clusters[recipe] for how we can use the connection string from `clusters get` to register new clusters for use with the shell.