Create and initialize a new cluster

Can be used by the following roles assigned at the organization scope:

• CLUSTER_ADMIN
• CLUSTER_CREATOR

POST /api/v1/clusters

cURL

cURL

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --json '{"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",
  "id": "35c4abb2-bb66-46d7-afed-25ebef5ed2aa",
  "name": "example-cluster",
  "operation_status": "UNSPECIFIED",
  "plan": "SERVERLESS",
  "regions": [
    {
      "internal_dns": "internal-free-tier7.gcp-us-central1.crdb.io",
      "name": "us-central1",
      "node_count": 0,
      "private_endpoint_dns": "private-free-tier7.gcp-us-central1.crdb.io",
      "sql_dns": "free-tier7.gcp-us-central1.crdb.io",
      "ui_dns": ""
    }
  ],
  "state": "CREATED",
  "updated_at": "2022-03-22T20:23:11.879593Z",
  "upgrade_status": "UPGRADE_AVAILABLE"
}

{
  "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.
• AZURE: The Azure cloud provider.

Available options: GCP, AWS, AZURE

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.
• AZURE: The Azure cloud provider.

Available options: GCP, AWS, AZURE

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: 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, DEDICATED_FULL_CLUSTER_RESTORE_RUNNING, DEDICATED_FULL_CLUSTER_RESTORE_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>

delete_protection · enum<string>

Available options: ENABLED, DISABLED

deleted_at · string<date-time>

egress_traffic_policy · enum<string>

• UNSPECIFIED: UNSPECIFIED signifies the egress traffic policy is unspecified.
• ERROR: 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.
• UPDATING: UPDATING signifies the egress traffic policy is updating.

Available options: UNSPECIFIED, ERROR, ALLOW_ALL, DEFAULT_DENY, UPDATING

network_visibility · enum<string>

Available options: PUBLIC, PRIVATE

parent_id · string

Preview: The parent ID is a folder ID. A "root" valued parent ID refers to a cluster at the root level.

sql_dns · string

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

updated_at · string<date-time>