Provision a CockroachDB Cloud Advanced cluster with the Terraform provider

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.

Before you begin

Before you start this tutorial, you must

• Install Terraform.
• Create a and in the CockroachDB Cloud Console, and assign it the Cluster Creator or Cluster Admin role at the organization scope. Refer to .

Create the Terraform configuration file

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

1. 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.

     You may also want to configure the settings your CockroachDB Advanced 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
     }
     

     You can modify the of managed backups only once with one of the following: the , the , or Terraform. To modify the setting again, contact the .

     For details on the backup_config settings, refer to .

2. Create an environment variable named COCKROACH_API_KEY. Copy the from the CockroachDB Cloud console and create the COCKROACH_API_KEY environment variable:

   export COCKROACH_API_KEY={API key}
   

   Where is the API key you copied from the CockroachDB Cloud Console.

Provision a cluster

1. 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.

2. Create the Terraform plan. This shows the actions the provider will take, but won’t perform them:

   terraform plan
   

3. 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 .

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

         serverless = {
           usage_limits = {
             provisioned_virtual_cpus = 2
           }
         }
     

2. Apply the template:

   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.

         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:

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

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 page to configure the managed backups for your CockroachDB Cloud cluster.