Create and initialize a new cluster

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

• CLUSTER_ADMIN
• CLUSTER_CREATOR

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"
      ],
      "usage_limits": {
        "provisioned_virtual_cpus": "2"
      }
    }
  }
}
'

200

{
  "account_id": "",
  "cidr_range": "172.28.0.0/14",
  "cloud_provider": "GCP",
  "cockroach_version": "v21.2.4",
  "config": {
    "serverless": {
      "routing_id": "example-cluster-1533",
      "upgrade_type": "AUTOMATIC",
      "usage_limits": {
        "provisioned_virtual_cpus": "2"
      }
    }
  },
  "created_at": "2022-03-22T20:23:11.285067Z",
  "creator_id": "7cde0cd9-0d8a-4008-8f90-45092ce8afc1",
  "id": "35c4abb2-bb66-46d7-afed-25ebef5ed2aa",
  "is_customer_cloud_account": false,
  "labels": {
    "cost_center": "12345",
    "env": "prod"
  },
  "name": "example-cluster",
  "operation_status": "UNSPECIFIED",
  "plan": "STANDARD",
  "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.

cidr_range · string · required

cidr_range is the IPv4 range in CIDR format that will be used by the cluster. It is only set on GCP Advanced tier clusters and is otherwise empty.

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

labels · object · required

labels are key-value pairs used to organize and categorize resources.

Show child attributes

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

• BASIC: The Basic plan includes essential operational features, is available in select regions, and offers on-demand capacity, making it ideal for small teams with unpredictable workloads.
• STANDARD: The Standard plan includes standard enterprise security and monitoring features, is available in all supported regions, and offers provisioned pricing, making it the default choice for most CockroachDB production workloads.
• ADVANCED: The Advanced plan is ideal for workloads with stringent isolation, compliance, and security requirements such as CMEK, PCI and HIPAA-readiness, and support for dedicated hardware. Customers are advised to have their account team and/or Cockroach Labs Support [e-mail] involved when provisioning Advanced clusters.

Available options: BASIC, STANDARD, ADVANCED

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

account_id is a cloud provider account ID representing the CockroachDB cluster. This ID can be used for setting up trust relationships with cloud resources. For GCP clusters, this value is a project name that can be used to construct principal service account names for authentication.

azure_cluster_identity_client_id · string

The client ID of the Azure cluster identity associated with this cluster. This field is only populated for clusters deployed on Azure and is used to support customer-managed encryption keys (CMEK).

created_at · string<date-time>

customer_cloud_account · object

Show child attributes

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>