Use the CockroachDB Cloud Terraform provider

On this page

Terraform 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 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 in the Terraform provider's GitHub repository.

Note:

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.

Watch a demo where we use Terraform to create a CockroachDB Serverless cluster here:

Before you begin

Before you start this tutorial, you must

Install Terraform.
Create a service account and API key in the CockroachDB Cloud Console, 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.

In a terminal create a new file named main.tf with the following contents:
```
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.
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:
```
export COCKROACH_API_KEY={API key}
```
Where {API key} is the API key you copied from the CockroachDB Cloud Console.

Provision a cluster

Initialize the provider:
```
terraform init -upgrade
```
This reads the main.tf configuration file. The -upgrade flag ensures you are using the latest version of the provider.
Create the Terraform plan. This shows the actions the provider will take, but won't perform them:
```
terraform plan
```
Create the cluster:
```
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.

Tip:

To change a cluster's plan in place between CockroachDB Basic and CockroachDB Standard, refer to Change a cluster's plan.

Note:

CockroachDB Standard is currently in Preview.

In this tutorial, you will create a CockroachDB Standard cluster.

In a terminal create a new file named main.tf with the following contents:
```
terraform {
  required_providers {
    cockroach = {
      source = "cockroachdb/cockroach"
    }
  }
}

resource "cockroach_cluster" "standard" {
  name           = "cockroach-standard"
  cloud_provider = "GCP"
  plan           = "STANDARD"
  serverless = {
    usage_limits = {
      provisioned_virtual_cpus = 2
    }
  }
  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-standard with a name for the cluster.
- Set cloud_provider to AWS AZURE, or GCP.
- Under usage_limits, set provisioned_virtual_cpus to the required maximum vCPUs for the cluster.
- Under regions, add the names of one or more regions for the cluster.
- To optionally enable deletion protection, set delete_protection to true.
You may also want to configure the managed backup settings your CockroachDB Standard cluster takes automatically. To do so, include the backup_config attribute in the cockroach_cluster resource:
```
backup_config = {
    enabled           = true
    frequency_minutes = 60
    retention_days    = 30
}
```
Note:

You can modify the retention of managed backups only once with one of the following: the Cloud Console, the Cloud API, or Terraform. To modify the setting again, contact the Cockroach Labs Support team.

For details on the backup_config settings, refer to Managed Backups.
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:
```
export COCKROACH_API_KEY={API key}
```
Where {API key} is the API key you copied from the CockroachDB Cloud Console.

Provision a cluster

Initialize the provider:
```
terraform init -upgrade
```
This reads the main.tf configuration file. The -upgrade flag ensures you are using the latest version of the provider.
Create the Terraform plan. This shows the actions the provider will take, but won't perform them:
```
terraform plan
```
Create the cluster:
```
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.

Tip:

To change a cluster's plan in place between CockroachDB Basic and CockroachDB Standard, refer to Change a cluster's plan.

In this tutorial, you will create a CockroachDB Advanced cluster.

In a terminal create a new file named main.tf with the following contents:
```
terraform {
  required_providers {
    cockroach = {
      source = "cockroachdb/cockroach"
    }
  }
}

resource "cockroach_cluster" "advanced" {
  name           = "cockroach-advanced"
  cloud_provider = "GCP"
  plan           = "ADVANCED"
  dedicated = {
    storage_gib = 15
    num_virtual_cpus = 4
  }
  regions = [
    {
      name       = "us-central1"
      node_count = 1
    }
  ]
  delete_protection = true
}
```
- 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-advanced with a name for the cluster.
- Set cloud_provider to AWS AZURE, or GCP.
- Under dedicated, set storage_gib to a value large enough to contain the cluster's expected data. Set num_virtual_cpus to the number of vCPUs per node.
- Under regions, add the names of one or more regions for the cluster and specify the node_count, or the number of nodes, per region.
- To optionally enable deletion protection, set delete_protection to true.
You may also want to configure the managed backup settings your CockroachDB Standard cluster takes automatically. To do so, include the backup_config attribute in the cockroach_cluster resource:
```
backup_config = {
    enabled           = true
    frequency_minutes = 60
    retention_days    = 30
}
```
Note:

You can modify the retention of managed backups only once with one of the following: the Cloud Console, the Cloud API, or Terraform. To modify the setting again, contact the Cockroach Labs Support team.

For details on the backup_config settings, refer to Managed Backups.
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:
```
export COCKROACH_API_KEY={API key}
```
Where {API key} is the API key you copied from the CockroachDB Cloud Console.

Provision a cluster

Initialize the provider:
```
terraform init -upgrade
```
This reads the main.tf configuration file. The -upgrade flag ensures you are using the latest version of the provider.
Create the Terraform plan. This shows the actions the provider will take, but won't perform them:
```
terraform plan
```
Create the cluster:
```
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.

Get information about a cluster

The terraform show command shows detailed information of your cluster resources.

terraform show

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.

Note:

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:

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.
```
    serverless = {
      usage_limits = {
        provisioned_virtual_cpus = 2
      }
    }
```
Apply the template:
```
terraform apply
```

To change a cluster's plan from CockroachDB Standard to CockroachDB Basic in place:

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.
```
    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.
Apply the template:
```
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:

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

Warning:

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:

terraform destroy

Enter yes when prompted to delete the cluster.

Next steps

Read the CockroachDB Cloud Terraform provider reference docs in the Terraform registry, which provide detailed information on the resources you can manage using Terraform.
Browse the example recipes in the Terraform Provider's GitHub repository.
Refer to the Managed Backups page to configure the managed backups for your CockroachDB Cloud cluster.

Pricing

Contact us

Sign In

Use the CockroachDB Cloud Terraform provider

Before you begin

Create the Terraform configuration file

Provision a cluster

Provision a cluster

Provision a cluster

Get information about a cluster

Change a cluster's plan

Delete a cluster

Next steps

Tell us about your experience

Thank you for your feedback!

Explore More Documentation:

Use the CockroachDB Cloud Terraform provider

Before you begin

Create the Terraform configuration file

Provision a cluster

Provision a cluster

Provision a cluster

Get information about a cluster

Change a cluster's plan

Delete a cluster

Next steps

Tell us about your experience

Select the problem area

Thank you for your feedback!

Explore More Documentation: