Provision a CockroachDB Cloud Standard cluster with the Terraform provider

​

Before you begin

• 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

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" "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 , set delete_protection to true.
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.

​

Before you begin

• 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

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" "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 , set delete_protection to true. You may also want to configure the 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
     }
     
     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.

​

Get information about a cluster

terraform show

​

Change a cluster’s plan

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
   

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
   

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

terraform destroy

​

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.