cURL

curl --request PATCH \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dedicated": {
    "hardware": {
      "machine_spec": {
        "num_virtual_cpus": 8
      }
    },
    "region_nodes": {
      "us-central1": 5,
      "us-west1": 3
    }
  }
}
'

{
  "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>"
}

Scale, edit or upgrade a cluster

In addition to adding nodes and changing cluster fields, the PATCH Cluster endpoint can be used to upgrade the cluster version. A cluster can be upgraded when its upgrade_status field is equal to UPGRADE_AVAILABLE. The /api/v1/cluster-versions endpoint can be used to enumerate versions which are valid to upgrade to. To begin the upgrade, PATCH the desired version into cockroach_version. For example {"cockroach_version": "v24.2"}. Multi-node clusters will undergo a rolling upgrade and will remain available, but single-node clusters will be briefly unavailable while the upgrade takes place. Upgrades will be finalized automatically after 72 hours but can be manually finalized by sending a PATCH containing {"upgrade_status": "FINALIZED"} to this endpoint. Before the cluster is finalized, it can be rolled back by either sending a PATCH of the previous version via cockroach_version or sending a PATCH containing {"upgrade_status": "ROLLBACK_RUNNING"}. Version upgrade operations cannot be performed simultaneously with other update operations. Only one of upgrade_status or cockroach_version is allowed in the request.

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

CLUSTER_ADMIN
CLUSTER_OPERATOR_WRITER

PATCH

api

clusters

{cluster_id}

cURL

curl --request PATCH \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dedicated": {
    "hardware": {
      "machine_spec": {
        "num_virtual_cpus": 8
      }
    },
    "region_nodes": {
      "us-central1": 5,
      "us-west1": 3
    }
  }
}
'

{
  "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.

Path Parameters

cluster_id

string

required

Body

application/json

cockroach_version

string

The desired CockroachDB major version for the cluster. It can be used to orchestrate version changes. Setting the version to a later version will initiate an upgrade to that version. After an upgrade is initiated but before it's finalized, setting the version back to the previous version will initiate a rollback.

dedicated

object

Show child attributes

delete_protection

enum<string>

Available options:

ENABLED,

DISABLED

labels

object

labels are key-value pairs used to organize and categorize resources. If the labels field is included in the request: Any existing labels on the cluster that are not included will be removed, and any new labels specified will be added. If the labels field is omitted from the request entirely, all existing labels will remain unchanged.

Show child attributes

parent_id

string

Preview: The parent ID is a folder ID. An empty string or "root" represents the root level.

plan

enum<string>

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.

Available options:

BASIC,

STANDARD,

ADVANCED

serverless

object

Show child attributes

upgrade_status

enum<string>

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

Response

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

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 support@cockroachlabs.com 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>

Delete a cluster and all of its data Get a formatted generic connection string for a cluster