terraform-provider-cockroach

README

Terraform provider for CockroachDB Cloud

terraform-provider-cockroach is the Terraform provider for the CockroachDB Cloud API [reference, getting started].

• Provision a CockroachDB Cloud Cluster with Terraform
• More information about CockroachDB
• More information about Terraform

For information on developing terraform-provider-cockroach see DEVELOPMENT.md.

Get Started

Warning: Use of private endpoints requires >=v1.7.6

If you intend to use this provider to provision private endpoints:

• AWS PrivateLink
• GCP Private Service Connect
• Azure Private Link

You must install/upgrade to version 1.7.6 or later.

Prerequisites

Before you use terraform-provider-cockroach you must install Terraform and git on your local machine.

Run the Serverless Example

1. In a terminal clone the terraform-provider-cockroach repository:

   git clone https://github.com/cockroachdb/terraform-provider-cockroach.git
   

2. Go to the examples/workflows/cockroach_serverless_cluster directory.

   cd examples/workflows/cockroach_serverless_cluster
   

3. The provider requires an API key set in 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=<YOUR_API_KEY>
   

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

4. In a text editor create a new file terraform.tfvars in cockroach_serverless_cluster with the following settings.

   cluster_name = "<cluster name>"
   sql_user_name = "<SQL user name>"
   sql_user_password = "<SQL user password>"
   

   Where:
   - <cluster name> is the name of the cluster you want to create.
   - <SQL user name> is the name of the SQL user you want to create.
   - <SQL user password> is the password for the SQL user you want to create.

5. Initialize the provider.

   terraform init
   

   This reads the main.tf configuration file, which contains the information on how the provider will create the Serverless cluster. The terraform.tfvars file sets the cluster name, SQL user name, and SQL user password.

6. Create the Terraform plan. This shows the actions the provider will take, but won't perform them.

   terraform plan
   

7. Create the cluster.

   terraform apply
   

   Enter yes when prompted to apply the plan and create the cluster.

8. (optional) Delete the cluster when you are done.

   terraform destroy
   

   Enter yes when prompted to delete the cluster.

Run the Dedicated Example

Running this example will incur charges to your CockroachDB account. It defaults to a minimal hardware spec, but please remember to run terraform destroy when you're done if you don't need to keep your cluster.

1. In a terminal clone the terraform-provider-cockroach repository:

   git clone https://github.com/cockroachdb/terraform-provider-cockroach.git
   

2. In a terminal go to the examples/workflows/cockroach_dedicated_cluster directory.

   cd examples/workflows/cockroach_dedicated_cluster
   

3. The provider requires an API key set in 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=<YOUR_API_KEY>
   

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

4. In a text editor create a new file terraform.tfvars in cockroach_dedicated_cluster with the following settings.

   cluster_name = "<cluster name>"
   database = "<database name>"
   sql_user_name = "<SQL user name>"
   sql_user_password = "<SQL user password>"
   cloud_provider = "<cloud provider>"
   cloud_provider_regions = ["<cloud provider region>"]
   cluster_node_count = <number of nodes>
   num_virtual_cpus = <number of VCPUs per node>
   storage_gib = <storage in GiB>
   allow_list_name = "<allow list name>"
   cidr_ip = "<allow list CIDR IP>"
   cidr_prefix_length = <allow list CIDR prefix length>
   os = "<OS name>"
   

   Where:
   - <cluster name> is the name of the cluster you want to create.
   - <database name> is the name that will be used for the database created within the cluster. This database is in addition to defaultdb which is created by default.
   - <SQL user name> is the name of the SQL user you want to create.
   - <SQL user password> is the password for the SQL user you want to create.
   - <cloud provider> is the cloud infrastructure provider. Possible values are GCP or AWS or AZURE.
   - <cloud provider region> is the region code or codes for the cloud infrastructure provider. For multi-region clusters, separate each region with a comma.
   - <number of nodes> is the number of nodes in each region. Cockroach Labs recommends at least 3 nodes per region, and the same number of nodes in each region for multi-region clusters.
   - <number of VCPUs per node> is the number of virtual CPUS assigned to each node. This number will dictate which machine type is used for your cluster nodes. Recommendations for choosing this value can be found here.
   - <storage in GiB> is the amount of storage specified in GiB.
   - <allow list name> is the name for the IP allow list. Use a descriptive name to identify the IP allow list. (i.e. "allow all" or "home network")
   - <allow list CIDR IP> is the Classless Inter-Domain Routing (CIDR) IP address base. (i.e. 123.123.123.123)
   - <allow list CIDR prefix length> is the CIDR prefix length. This should be a number from 0 to 32. Use 32 to only allow the single IP Address passed in cidr_ip.
   - <OS name> is the name of the OS that will be used to connect from for connection string output. Possible values are ('WINDOWS', 'MAC', and 'LINUX').

5. Initialize the provider.

   terraform init
   

   This reads the main.tf configuration file, which contains the information on how the provider will create the Serverless cluster. The terraform.tfvars file sets the cluster name, SQL user name, and SQL user password.

6. Create the Terraform plan. This shows the actions the provider will take, but won't perform them.

   terraform plan
   

7. Create the cluster.

   terraform apply
   

   Enter yes when prompted to apply the plan and create the cluster.

8. (optional) Delete the cluster when you are done.

   terraform destroy
   

   Enter yes when prompted to delete the cluster.