# Use the CockroachDB Cloud 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.

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.

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

       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:

       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.

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.

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

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:

       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:

       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.

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.

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

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:

       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:

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

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