Create and initialize a new cluster.

POST /api/v1/clusters

cURL

cURL

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"name":"test-cluster","provider":"GCP","spec":{"serverless":{"regions":["us-central1"],"spend_limit":0}}}'

200

{
  "id": "35c4abb2-bb66-46d7-afed-25ebef5ed2aa",
  "name": "example-cluster",
  "cockroach_version": "v21.2.4",
  "plan": "SERVERLESS",
  "cloud_provider": "GCP",
  "account_id": "",
  "state": "CREATED",
  "creator_id": "7cde0cd9-0d8a-4008-8f90-45092ce8afc1",
  "operation_status": "CLUSTER_STATUS_UNSPECIFIED",
  "config": {
    "serverless": {
      "spend_limit": 0,
      "routing_id": "example-cluster-1533"
    }
  },
  "regions": [
    {
      "name": "us-central1",
      "sql_dns": "free-tier7.gcp-us-central1.crdb.io",
      "ui_dns": "",
      "node_count": 0
    }
  ],
  "created_at": "2022-03-22T20:23:11.285067Z",
  "updated_at": "2022-03-22T20:23:11.879593Z",
  "deleted_at": null
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

name · string · required

provider · enum<string> · default: CLOUD_PROVIDER_UNSPECIFIED · required

• GCP: The Google Cloud Platform cloud provider.
• AWS: The Amazon Web Services cloud provider.

Available options: CLOUD_PROVIDER_UNSPECIFIED, GCP, AWS

spec · object · required

Show child attributes

Response

200

application/json

A successful response.

id · string · required

name · string · required

cockroach_version · string · required

plan · enum<string> · default: PLAN_UNSPECIFIED · required

• DEDICATED: A paid plan that offers dedicated hardware in any location.
• CUSTOM: A plan option that is used for clusters whose machine configs are not supported in self-service. All INVOICE clusters are under this plan option.
• SERVERLESS: A paid plan that runs on shared hardware and caps the users' maximum monthly spending to a user-specified (possibly 0) amount.

Available options: PLAN_UNSPECIFIED, DEDICATED, CUSTOM, SERVERLESS

cloud_provider · enum<string> · default: CLOUD_PROVIDER_UNSPECIFIED · required

• GCP: The Google Cloud Platform cloud provider.
• AWS: The Amazon Web Services cloud provider.

Available options: CLOUD_PROVIDER_UNSPECIFIED, GCP, AWS

state · enum<string> · default: CLUSTER_STATE_UNSPECIFIED · required

• LOCKED: An exclusive operation is being performed on this cluster. Other operations should not proceed if they did not set a cluster into the LOCKED state.

Available options: CLUSTER_STATE_UNSPECIFIED, CREATING, CREATED, CREATION_FAILED, DELETED, LOCKED

creator_id · string · required

operation_status · enum<string> · default: CLUSTER_STATUS_UNSPECIFIED · required

Available options: CLUSTER_STATUS_UNSPECIFIED, CRDB_MAJOR_UPGRADE_RUNNING, CRDB_MAJOR_UPGRADE_FAILED, CRDB_MAJOR_ROLLBACK_RUNNING, CRDB_MAJOR_ROLLBACK_FAILED, CRDB_PATCH_RUNNING, CRDB_PATCH_FAILED, CRDB_SCALE_RUNNING, CRDB_SCALE_FAILED, MAINTENANCE_RUNNING, CRDB_INSTANCE_UPDATE_RUNNING, CRDB_INSTANCE_UPDATE_FAILED, CRDB_EDIT_CLUSTER_RUNNING, CRDB_EDIT_CLUSTER_FAILED, CRDB_CMEK_OPERATION_RUNNING, CRDB_CMEK_OPERATION_FAILED, TENANT_RESTORE_RUNNING, TENANT_RESTORE_FAILED

config · object · required

Show child attributes

regions · object[] · required

Show child attributes

account_id · string

created_at · string<date-time>

updated_at · string<date-time>

deleted_at · string<date-time>