cURL

curl --request PATCH \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --json '{"dedicated":{"hardware":{"machine_spec":{"machine_type":"n2-standard-8"}},"region_nodes":{"us-central1":5,"us-west1":3}}}'

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

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. To begin the upgrade, PATCH {"upgrade_status": "MAJOR_UPGRADE_RUNNING"} to this endpoint. 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 sending a PATCH containing {"upgrade_status": "ROLLBACK_RUNNING"}. Version upgrade operations cannot be performed simultaneously with other update operations.

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 REPLACE_BEARER_TOKEN' \
  --json '{"dedicated":{"hardware":{"machine_spec":{"machine_type":"n2-standard-8"}},"region_nodes":{"us-central1":5,"us-west1":3}}}'

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

Path Parameters

cluster_id

string

required

Body

application/json

dedicated

object

Show child attributes

delete_protection

enum<string>

Available options:

ENABLED,

DISABLED

parent_id

string

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

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.

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

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>

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

Overview

Endpoints

Scale, edit or upgrade a cluster

Authorizations

Path Parameters

Body

Response