> ## Documentation Index > Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create and initialize a new cluster ## OpenAPI ````yaml /openapi/cloud/2022-09-20.json post /api/v1/clusters openapi: 3.0.0 info: contact: email: support@cockroachlabs.com name: Cockroach Labs Support url: https://support.cockroachlabs.com description: >- This is a preview version of the Cloud API. The interface and output is subject to change, and there may be bugs. title: CockroachDB Cloud API version: '2022-09-20' servers: - url: https://cockroachlabs.cloud security: - Bearer: [] tags: - name: CockroachCloud externalDocs: description: Use the CockroachDB Cloud API url: https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api paths: /api/v1/clusters: post: tags: - CockroachCloud summary: Create and initialize a new cluster operationId: CockroachCloud_CreateCluster requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateClusterRequest' responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/Cluster' '400': description: Returned when a request field is invalid. content: application/json: schema: {} '401': description: Returned when the token bearer cannot be authenticated. content: application/json: schema: {} '403': description: >- Returned when the user does not have permission to access the resource. content: application/json: schema: {} '404': description: Returned when the resource does not exist. content: application/json: schema: {} '500': description: Server error content: application/json: schema: {} default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Status' x-codeSamples: - lang: curl source: |- curl --request POST \ --url https://cockroachlabs.cloud/api/v1/clusters \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'content-type: application/json' \ --data '{"name":"test-cluster","provider":"GCP","spec":{"serverless":{"regions":["us-central1"],"spend_limit":0}}}' components: schemas: CreateClusterRequest: type: object properties: name: description: |- Name must be 6-20 characters in length and can include numbers, lowercase letters, and dashes (but no leading or trailing dashes). type: string provider: $ref: '#/components/schemas/api.CloudProvider' spec: $ref: '#/components/schemas/CreateClusterSpecification' example: name: test-cluster provider: GCP spec: serverless: regions: - us-central1 spend_limit: 0 required: - name - provider - spec title: CreateClusterRequest Cluster: type: object properties: account_id: type: string cloud_provider: $ref: '#/components/schemas/api.CloudProvider' cockroach_version: type: string config: $ref: '#/components/schemas/ClusterConfig' created_at: type: string format: date-time creator_id: type: string deleted_at: type: string format: date-time egress_traffic_policy: $ref: '#/components/schemas/EgressTrafficPolicy' id: type: string name: type: string network_visibility: $ref: '#/components/schemas/NetworkVisiblity' operation_status: $ref: '#/components/schemas/ClusterStatusType' plan: $ref: '#/components/schemas/Plan' regions: type: array items: $ref: '#/components/schemas/Region' sql_dns: description: sql_dns is the DNS name of SQL interface of the cluster. type: string state: $ref: '#/components/schemas/ClusterStateType' updated_at: type: string format: date-time upgrade_status: $ref: '#/components/schemas/ClusterUpgradeStatus' example: 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 required: - id - name - cockroach_version - upgrade_status - plan - cloud_provider - state - creator_id - operation_status - config - regions Status: type: object properties: code: type: integer format: int32 details: type: array items: $ref: '#/components/schemas/Any' message: type: string api.CloudProvider: description: |2- - GCP: The Google Cloud Platform cloud provider. - AWS: The Amazon Web Services cloud provider. type: string enum: - GCP - AWS CreateClusterSpecification: type: object properties: dedicated: $ref: '#/components/schemas/DedicatedClusterCreateSpecification' serverless: $ref: '#/components/schemas/ServerlessClusterCreateSpecification' ClusterConfig: type: object properties: dedicated: $ref: '#/components/schemas/DedicatedHardwareConfig' serverless: $ref: '#/components/schemas/ServerlessClusterConfig' EgressTrafficPolicy: description: >2- - 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. type: string enum: - POLICY_UNSPECIFIED - POLICY_ERROR - ALLOW_ALL - DEFAULT_DENY - POLICY_UPDATING NetworkVisiblity: type: string enum: - NETWORK_VISIBILITY_PUBLIC - NETWORK_VISIBILITY_PRIVATE ClusterStatusType: type: string enum: - 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: description: >2- - 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. type: string enum: - DEDICATED - CUSTOM - SERVERLESS Region: type: object properties: internal_dns: description: >- internal_dns is the internal DNS name of the cluster within the cloud provider's network. It is used to connect to the cluster with PrivateLink or VPC peering. type: string name: type: string node_count: description: node_count will be 0 for Serverless clusters. type: integer format: int32 primary: description: >- primary is true only for the primary region in a Multi Region Serverless cluster. type: boolean sql_dns: description: >- sql_dns is the DNS name of SQL interface of the cluster. It is used to connect to the cluster with IP allowlisting. type: string ui_dns: description: >- ui_dns is the DNS name used when connecting to the DB Console for the cluster. type: string required: - name - sql_dns - ui_dns - node_count - internal_dns ClusterStateType: description: >2- - 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. type: string enum: - CREATING - CREATED - CREATION_FAILED - DELETED - LOCKED ClusterUpgradeStatus: description: |2- - 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. type: string enum: - FINALIZED - MAJOR_UPGRADE_RUNNING - UPGRADE_AVAILABLE - PENDING_FINALIZATION - ROLLBACK_RUNNING Any: description: >- `Any` contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message. Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type. Example 1: Pack and unpack a message in C++. Foo foo = ...; Any any; any.PackFrom(foo); ... if (any.UnpackTo(&foo)) { ... } Example 2: Pack and unpack a message in Java. Foo foo = ...; Any any = Any.pack(foo); ... if (any.is(Foo.class)) { foo = any.unpack(Foo.class); } Example 3: Pack and unpack a message in Python. foo = Foo(...) any = Any() any.Pack(foo) ... if any.Is(Foo.DESCRIPTOR): any.Unpack(foo) ... Example 4: Pack and unpack a message in Go foo := &pb.Foo{...} any, err := ptypes.MarshalAny(foo) ... foo := &pb.Foo{} if err := ptypes.UnmarshalAny(any, foo); err != nil { ... } The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z". JSON ==== The JSON representation of an `Any` value uses the regular representation of the deserialized, embedded message, with an additional field `@type` which contains the type URL. Example: package google.profile; message Person { string first_name = 1; string last_name = 2; } { "@type": "type.googleapis.com/google.profile.Person", "firstName": , "lastName": } If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field `value` which holds the custom JSON in addition to the `@type` field. Example (for message [google.protobuf.Duration][]): { "@type": "type.googleapis.com/google.protobuf.Duration", "value": "1.212s" } type: object properties: '@type': description: >- A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted). In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows: * If no scheme is provided, `https` is assumed. * An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error. * Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.) Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics. type: string additionalProperties: {} DedicatedClusterCreateSpecification: type: object properties: cockroach_version: description: |- The CockroachDB version for the cluster. The current version is used if omitted. type: string hardware: $ref: '#/components/schemas/DedicatedHardwareCreateSpecification' network_visibility: $ref: '#/components/schemas/NetworkVisiblity' region_nodes: description: |- Region keys should match the cloud provider's zone code. For example, for Oregon, set region_name to "us-west2" for GCP and "us-west-2" for AWS. Values represent the node count. type: object additionalProperties: type: integer format: int32 restrict_egress_traffic: description: >- Preview: RestrictEgressTraffic if set, results in an egress traffic policy of default-deny at creation time. type: boolean required: - region_nodes - hardware ServerlessClusterCreateSpecification: type: object properties: primary_region: description: |- Preview: Specify which region should be made the primary region. This is only applicable to multi-region Serverless clusters. This field is required if you create the cluster in more than one region. type: string regions: description: |- Region values should match the cloud provider's zone code. For example, for Oregon, set region_name to "us-west2" for GCP and "us-west-2" for AWS. type: array items: type: string spend_limit: description: >- spend_limit is the maximum monthly charge for a cluster, in US cents. type: integer format: int32 usage_limits: $ref: '#/components/schemas/UsageLimits' required: - regions DedicatedHardwareConfig: type: object properties: disk_iops: description: |- disk_iops is the number of disk I/O operations per second that are permitted on each node in the cluster. Zero indicates the cloud provider-specific default. type: integer format: int32 machine_type: description: |- machine_type is the machine type identifier within the given cloud provider, ex. m5.xlarge, n2-standard-4. type: string memory_gib: description: memory_gib is the memory GiB per node in the cluster. type: number format: float num_virtual_cpus: description: >- num_virtual_cpus is the number of virtual CPUs per node in the cluster. type: integer format: int32 storage_gib: description: storage_gib is the number of storage GiB per node in the cluster. type: integer format: int32 required: - machine_type - num_virtual_cpus - storage_gib - memory_gib - disk_iops ServerlessClusterConfig: type: object properties: routing_id: description: routing_id is used to identify the cluster in a connection string. type: string spend_limit: description: >- spend_limit is the maximum monthly charge for a cluster, in US cents. type: integer format: int32 usage_limits: $ref: '#/components/schemas/UsageLimits' required: - routing_id DedicatedHardwareCreateSpecification: type: object properties: disk_iops: description: |- disk_iops is the number of disk I/O operations per second that are permitted on each node in the cluster. Zero indicates the cloud provider-specific default. Only available for AWS clusters. type: integer format: int32 machine_spec: $ref: '#/components/schemas/DedicatedMachineTypeSpecification' storage_gib: description: >- storage_gib is the number of storage GiB per node in the cluster. Zero indicates default to the lowest storage GiB available given machine specs. type: integer format: int32 required: - machine_spec - storage_gib UsageLimits: type: object properties: request_unit_limit: description: >- request_unit_limit is the maximum number of request units that the cluster can consume during the month. If this limit is exceeded, then the cluster is disabled until the limit is increased, or until the beginning of the next month when more free request units are granted. It is an error for this to be zero. type: string format: int64 storage_mib_limit: description: >- storage_mib_limit is the maximum number of Mebibytes of storage that the cluster can have at any time during the month. If this limit is exceeded, then the cluster is throttled; only one SQL connection is allowed at a time, with the expectation that it is used to delete data to reduce storage usage. If is an error for this to be zero. type: string format: int64 required: - request_unit_limit - storage_mib_limit DedicatedMachineTypeSpecification: type: object properties: machine_type: description: |- machine_type is the machine type identifier within the given cloud provider, ex. m5.xlarge, n2-standard-4. type: string num_virtual_cpus: description: |- num_virtual_cpus may be used to automatically select a machine type according to the desired number of vCPUs. type: integer format: int32 securitySchemes: Bearer: type: http scheme: bearer ````