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 <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "test-cluster",
  "provider": "GCP",
  "spec": {
    "serverless": {
      "regions": [
        "us-central1"
      ],
      "spend_limit": 0
    }
  }
}
'

200

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

{
  "code": 123,
  "details": [
    {
      "@type": "<string>"
    }
  ],
  "message": "<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

Name must be 6-20 characters in length and can include numbers, lowercase letters, and dashes (but no leading or trailing dashes).

provider · enum<string> · required

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

Available options: GCP, AWS

spec · object · required

Show child attributes

Response

200

application/json

A successful response.

cloud_provider · enum<string> · required

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

Available options: GCP, AWS

cockroach_version · string · required

config · object · required

Show child attributes

creator_id · string · required

id · string · required

name · string · required

operation_status · enum<string> · 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, CRDB_LOG_EXPORT_OPERATION_RUNNING, CRDB_LOG_EXPORT_OPERATION_FAILED, CRDB_CLUSTER_DISRUPTION_RUNNING, CRDB_CLUSTER_DISRUPTION_FAILED, CRDB_REPAVE_RUNNING, CRDB_REPAVE_FAILED, CRDB_CUSTOM_CLIENT_CA_RUNNING, CRDB_CUSTOM_CLIENT_CA_FAILED

plan · enum<string> · 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: DEDICATED, CUSTOM, SERVERLESS

regions · object[] · required

Show child attributes

state · enum<string> · 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: CREATING, CREATED, CREATION_FAILED, DELETED, LOCKED

upgrade_status · enum<string> · required

• FINALIZED: The cluster is running the latest available CockroachDB version, and all upgrades have been finalized.
• MAJOR_UPGRADE_RUNNING: An major version upgrade is currently in progress.
• UPGRADE_AVAILABLE: An upgrade is available. If preview builds are enabled for the parent organization, this could indicate that a preview upgrade is available.
• PENDING_FINALIZATION: An upgrade is complete, but pending finalization. Upgrades are automatically finalized after 72 hours. For more information, see https://www.cockroachlabs.com/docs/stable/upgrade-cockroach-version.html
• ROLLBACK_RUNNING: A rollback operation is currently in progress.

Available options: FINALIZED, MAJOR_UPGRADE_RUNNING, UPGRADE_AVAILABLE, PENDING_FINALIZATION, ROLLBACK_RUNNING

account_id · string

created_at · string<date-time>

deleted_at · string<date-time>

egress_traffic_policy · enum<string>

• POLICY_UNSPECIFIED: POLICY_UNSPECIFIED signifies the egress traffic policy is unspecified.
• POLICY_ERROR: POLICY_ERROR signifies there has been an internal server error during an update to the egress traffic policy.
• ALLOW_ALL: ALLOW_ALL signifies all outbound connections from CockroachDB are allowed.
• DEFAULT_DENY: DEFAULT_DENY signifies that CockroachDB can only initiate network connections to destinations explicitly allowed by the user or CockroachDB Cloud operators.
• POLICY_UPDATING: POLICY_UPDATING signifies the egress traffic policy is updating.

Available options: POLICY_UNSPECIFIED, POLICY_ERROR, ALLOW_ALL, DEFAULT_DENY, POLICY_UPDATING

network_visibility · enum<string>

Available options: NETWORK_VISIBILITY_PUBLIC, NETWORK_VISIBILITY_PRIVATE

sql_dns · string

sql_dns is the DNS name of SQL interface of the cluster.

updated_at · string<date-time>