curl --request POST \
--url https://cockroachlabs.cloud/api/v1/virtual-cluster-workspaces/{workspace_id}/clusters \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--json '{"name":"reporting","primary_region":"us-east-1","regions":["us-east-1","us-west-2"]}'{
"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>"
}Create a virtual cluster in a workspace
Can be used by the following roles assigned at the organization or folder scope:
- CLUSTER_ADMIN
- CLUSTER_CREATOR
Setting a custom virtual_cpu_burst_limit for this cluster additionally requires a role with edit permission assigned on the host cluster backing the workspace.
curl --request POST \
--url https://cockroachlabs.cloud/api/v1/virtual-cluster-workspaces/{workspace_id}/clusters \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--json '{"name":"reporting","primary_region":"us-east-1","regions":["us-east-1","us-west-2"]}'{
"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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The unique identifier of the workspace to create the cluster in.
Body
The name of the cluster.
ENABLED, DISABLED labels are key-value pairs used to organize and categorize resources.
Show child attributes
Show child attributes
The parent ID is a folder ID. An empty string or "root" will create a cluster at the root level.
Specify which region should be made the primary region. This field is required if the cluster spans more than one region, and must be one of the regions the cluster spans.
regions is the subset of the workspace's regions to create this cluster in. Omit to use every region in the workspace. Gives an error if a region is specified that is not in the workspace. Values are the cloud provider's region codes, for example "us-east-1".
Sets a custom value for the maximum vCPUs this cluster may use at once. Omit to inherit the workspace's default. Setting a custom vCPU burst limit requires edit permission on the workspace.
Response
A successful response.
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.
- GCP: The Google Cloud Platform cloud provider.
- AWS: The Amazon Web Services cloud provider.
- AZURE: The Azure cloud provider.
GCP, AWS, AZURE Show child attributes
Show child attributes
labels are key-value pairs used to organize and categorize resources.
Show child attributes
Show child attributes
- UNSPECIFIED: No ongoing operation. The cluster is running normally.
- CRDB_MAJOR_UPGRADE_RUNNING: A major CockroachDB version upgrade is in progress.
- CRDB_MAJOR_UPGRADE_FAILED: A major CockroachDB version upgrade has failed.
- CRDB_MAJOR_ROLLBACK_RUNNING: A major CockroachDB version rollback is in progress.
- CRDB_MAJOR_ROLLBACK_FAILED: A major CockroachDB version rollback has failed.
- CRDB_PATCH_RUNNING: A CockroachDB patch version update is in progress.
- CRDB_PATCH_FAILED: A CockroachDB patch version update has failed.
- CRDB_SCALE_RUNNING: A cluster scale operation is in progress.
- CRDB_SCALE_FAILED: A cluster scale operation has failed.
- MAINTENANCE_RUNNING: A cluster maintenance operation is in progress.
- CRDB_INSTANCE_UPDATE_RUNNING: A cluster instance update is in progress.
- CRDB_INSTANCE_UPDATE_FAILED: A cluster instance update has failed.
- CRDB_EDIT_CLUSTER_RUNNING: A cluster edit operation is in progress.
- CRDB_EDIT_CLUSTER_FAILED: A cluster edit operation has failed.
- CRDB_CMEK_OPERATION_RUNNING: A CMEK key operation is in progress.
- CRDB_CMEK_OPERATION_FAILED: A CMEK key operation has failed.
- TENANT_RESTORE_RUNNING: A tenant restore operation is in progress.
- TENANT_RESTORE_FAILED: A tenant restore operation has failed.
- CRDB_LOG_EXPORT_OPERATION_RUNNING: A log export configuration operation is in progress.
- CRDB_LOG_EXPORT_OPERATION_FAILED: A log export configuration operation has failed.
- CRDB_CLUSTER_DISRUPTION_RUNNING: A cluster disruption operation is in progress.
- CRDB_CLUSTER_DISRUPTION_FAILED: A cluster disruption operation has failed.
- CRDB_REPAVE_RUNNING: A cluster node repave operation is in progress.
- CRDB_REPAVE_FAILED: A cluster node repave operation has failed.
- CRDB_CUSTOM_CLIENT_CA_RUNNING: A custom client CA certificate operation is in progress.
- CRDB_CUSTOM_CLIENT_CA_FAILED: A custom client CA certificate operation has failed.
- DEDICATED_FULL_CLUSTER_RESTORE_RUNNING: A dedicated cluster full restore is in progress.
- DEDICATED_FULL_CLUSTER_RESTORE_FAILED: A dedicated cluster full restore has failed.
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 Show child attributes
Show child attributes
- 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.
CREATING, CREATED, CREATION_FAILED, DELETED, LOCKED - 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.
FINALIZED, MAJOR_UPGRADE_RUNNING, UPGRADE_AVAILABLE, PENDING_FINALIZATION, ROLLBACK_RUNNING account_id identifies the cloud provider account to grant access to when setting up a trust relationship between this cluster and your own cloud resources. Its form follows the cloud provider: an account ID on AWS, a project ID on GCP, and a subscription ID on Azure. On GCP the project ID also forms the principal service account names used for authentication.
Which account this is depends on how the cluster is hosted. An Advanced cluster or a host cluster reports the account it runs in, which is the account to grant access to when configuring CMEK. A virtual cluster reports the account its host cluster runs in, since it shares that hardware. A Basic or Standard cluster runs on hardware shared with other organizations, so it instead reports an account CockroachDB Cloud operates on its behalf, which is the account to grant access to when configuring metrics export or log export.
Empty when no account applies to the cluster, so treat an empty value as "not applicable" rather than an error.
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).
Show child attributes
Show child attributes
ENABLED, DISABLED A Continuum edition, which determines the capabilities a cluster's license grants. Editions are available only to clusters in Cockroach Continuum organizations, and a request that sets an edition from a non-Continuum organization is rejected. Editions and plans are mutually exclusive, so a cluster reports one or the other, never both.
- STANDARD: The Standard edition grants the Standard capability set. See Editions and add-ons for the capabilities each edition includes.
- MISSION_CRITICAL: The Mission Critical edition grants the Standard capability set plus the Mission Critical capabilities. See Editions and add-ons for the capabilities each edition includes.
STANDARD, MISSION_CRITICAL - 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.
UNSPECIFIED, ERROR, ALLOW_ALL, DEFAULT_DENY, UPDATING PUBLIC, PRIVATE Preview: The parent ID is a folder ID. A "root" valued parent ID refers to a cluster at the root level.
- 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 support@cockroachlabs.com involved when provisioning Advanced clusters.
BASIC, STANDARD, ADVANCED sql_dns is the DNS name of SQL interface of the cluster.