> ## 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.
# Provision a CockroachDB Cloud Basic cluster with the Terraform provider
export const InternalLink = ({version, path = "", children, ...props}) => {
let detectedVersion = version || "stable";
if (typeof window !== 'undefined' && !version) {
const match = window.location.pathname.match(/\/docs\/([^/]+)/);
if (match) {
detectedVersion = match[1];
}
}
const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
return
{children}
;
};
[Terraform](https://terraform.io/) is an infrastructure-as-code provisioning tool that uses configuration files to define application and network resources. You can provision CockroachDB Cloud clusters and cluster resources by using the [CockroachDB Cloud Terraform provider](https://registry.terraform.io/providers/cockroachdb/cockroach) in your Terraform configuration files.
This page shows how to use the CockroachDB Cloud Terraform provider to create and manage clusters in CockroachDB Cloud. This page is not exhaustive; you can browse an extensive set of [example recipes](https://github.com/cockroachdb/terraform-provider-cockroach/tree/main/examples) in the Terraform provider's GitHub repository.
If you used the Terraform provider to manage CockroachDB Serverless clusters that have been migrated to CockroachDB Basic, your recipes must be updated to work with CockroachDB Basic.
## Before you begin
Before you start this tutorial, you must
* [Install Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli).
* Create a service account and API key in the [CockroachDB Cloud Console](https://cockroachlabs.cloud/), and assign it the Cluster Creator or Cluster Admin role at the organization scope. Refer to Service Accounts.
## Create the Terraform configuration file
In this tutorial, you will create a CockroachDB Basic cluster.
1. In a terminal create a new file named `main.tf` with the following contents:
```hcl theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
terraform {
required_providers {
cockroach = {
source = "cockroachdb/cockroach"
}
}
}
resource "cockroach_cluster" "basic" {
name = "cockroach-basic"
cloud_provider = "GCP"
plan = "BASIC"
serverless = {}
regions = [
{
name = "us-east1"
}
]
delete_protection = false
}
```
* Optionally, include the `version` attribute in the `cockroach` nested block to specify a version of the provider. If you do not include the `version` attribute, Terraform will use the latest provider version.
* Replace `cockroach-basic` with a name for the cluster.
* Set `cloud_provider` to `AWS` `AZURE`, or `GCP`.
* Under `serverless {}`, optionally set values for `resource_unit_limit` and `storage_mib_limits`.
* Under `regions`, add the names of one or more regions for the cluster.
* To optionally enable deletion protection, set `delete_protection` to `true`.
2. Create an environment variable named `COCKROACH_API_KEY`. Copy the API key from the CockroachDB Cloud console and create the `COCKROACH_API_KEY` environment variable:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
export COCKROACH_API_KEY={API key}
```
Where {'{API key}'} is the API key you copied from the CockroachDB Cloud Console.
## Provision a cluster
1. Initialize the provider:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
terraform init -upgrade
```
This reads the `main.tf` configuration file. The `-upgrade` flag ensures you are using the latest version of the provider.
2. Create the Terraform plan. This shows the actions the provider will take, but won't perform them:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
terraform plan
```
3. Create the cluster:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
terraform apply
```
Enter `yes` when prompted to apply the plan and create the cluster.
Terraform reports the actions it will take. Verify the details, then type `yes` to apply the changes.
To change a cluster's plan in place between CockroachDB Basic and CockroachDB Standard, refer to [Change a cluster's plan](#change-a-clusters-plan).
## Change a cluster's plan
To change a CockroachDB Basic cluster's plan to CockroachDB Standard in place, or to change a CockroachDB Standard cluster to CockroachDB Basic using Terraform or the CockroachDB Cloud API.
To migrate between CockroachDB Advanced and either CockroachDB Standard or CockroachDB Basic, you must create and configure a new cluster, create a self-managed backup of the existing cluster's data, and restore the backup to the new cluster. Refer to Back up a CockroachDB Cloud cluster and restore into a new cluster. Migration in place is not supported.
To migrate from CockroachDB Basic to CockroachDB Standard in place:
1. Edit the cluster's Terraform template:
* Change `plan` to `STANDARD`.
* Replace the contents of `serverless {}` (which may be empty) with the provisioned vCPUs for the cluster. This field is required for CockroachDB Standard. It is not possible to set storage limitations on CockroachDB Standard.
```hcl theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
serverless = {
usage_limits = {
provisioned_virtual_cpus = 2
}
}
```
2. Apply the template:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
terraform apply
```
To change a cluster's plan from CockroachDB Standard to CockroachDB Basic in place:
1. Edit the cluster's Terraform template:
* Change `plan` to `BASIC`.
* Replace the contents of `serverless {...}` with optional limits for Request Units and Storage. The `provisioned_virtual_cpus` field is not supported on CockroachDB Basic.
```hcl theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
serverless = {
usage_limits = {
request_unit_limit = 4000
storage_mib_limit = 2000
}
}
```
* Remove configurations for features that are unsupported on CockroachDB Basic, such as private connectivity. Otherwise, applying the template will fail.
2. Apply the template:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
terraform apply
```
To use the CockroachDB Cloud API to switch a cluster's plan in place between Basic and Standard, send a `PATCH` request to the `clusters/{cluster_id}` endpoint updating the `plan` and `serverless.usage_limits` as needed. The following example sets the `plan` to `STANDARD` and updates the `usage_limits` to provision VCPUs as required for a Standard plan:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request PATCH \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \
--header "Authorization: Bearer <your_api_key>" \
--json '{"plan":"STANDARD","serverless":{"usage_limits":{"provisioned_virtual_cpus": 2}}}'
```
## Delete a cluster
Sending a `destory` command permanently deletes the cluster and all the data within the cluster. Deleted clusters can not be restored.
If you want to delete a cluster managed by Terraform, run the following command:
```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
terraform destroy
```
Enter `yes` when prompted to delete the cluster.
## Next steps
* Read the [CockroachDB Cloud Terraform provider reference docs](https://registry.terraform.io/providers/cockroachdb/cockroach/latest/docs) in the Terraform registry, which provide detailed information on the resources you can manage using Terraform.
* Browse the [example recipes](https://github.com/cockroachdb/terraform-provider-cockroach/tree/main/examples) in the Terraform Provider's GitHub repository.
* Refer to the Managed Backups page to configure the managed backups for your CockroachDB Cloud cluster.