Scale or edit a cluster

PATCH /api/v1/clusters/{cluster_id}

cURL

cURL

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

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",
  "deleted_at": null,
  "id": "35c4abb2-bb66-46d7-afed-25ebef5ed2aa",
  "name": "example-cluster",
  "operation_status": "CLUSTER_STATUS_UNSPECIFIED",
  "plan": "SERVERLESS",
  "regions": [
    {
      "name": "us-central1",
      "node_count": 0,
      "sql_dns": "free-tier7.gcp-us-central1.crdb.io",
      "ui_dns": ""
    }
  ],
  "state": "CREATED",
  "updated_at": "2022-03-22T20:23:11.879593Z",
  "upgrade_status": "USING_LATEST"
}

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

Set upgrade_status to 'UPGRADE_RUNNING' to start an upgrade. 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, or can be manually finalized by setting the value to 'FINALIZED'. Before the cluster is finalized, it can be rolled back by setting the value to 'ROLLBACK_RUNNING'. Version upgrade operations cannot be performed simultaneously with other update operations.

dedicated · object

Show child attributes

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

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.

Available options: GCP, AWS

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: CLUSTER_STATUS_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

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>

deleted_at · string<date-time>

egress_traffic_policy · enum<string>

• POLICY_UNSPECIFIED: POLICY_UNSPECIFIED signifies the egress traffic policy is unspecified.
• POLICY_ERROR: POLICY_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.
• POLICY_UPDATING: POLICY_UPDATING signifies the egress traffic policy is updating.

Available options: POLICY_UNSPECIFIED, POLICY_ERROR, ALLOW_ALL, DEFAULT_DENY, POLICY_UPDATING

network_visibility · enum<string>

Available options: NETWORK_VISIBILITY_PUBLIC, NETWORK_VISIBILITY_PRIVATE

sql_dns · string

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

updated_at · string<date-time>