terraform-provider-cockroach is the Terraform provider for the CockroachDB Cloud API [reference, getting started].
For information on developing terraform-provider-cockroach see DEVELOPMENT.md.
We do not use GitHub Issues for tracking bugs or feature requests. If you encounter a problem or have a request, please submit it through our support portal:
https://support.cockroachlabs.com/hc/en-us
This ensures that reports are properly triaged and addressed by our team.
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.
Before you use terraform-provider-cockroach you must install Terraform and git on your local machine.
In a terminal clone the terraform-provider-cockroach repository:
~~~ shell git clone https://github.com/cockroachdb/terraform-provider-cockroach.git ~~~
Go to the examples/workflows/cockroach_serverless_cluster directory.
~~~ shell cd examples/workflows/cockroach_serverless_cluster ~~~
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.
~~~ shell export COCKROACH_API_KEY= ~~~
Where <your API key> is the API key you copied from the CockroachDB Cloud Console.
In a text editor create a new file terraform.tfvars in cockroach_serverless_cluster with the following settings.
~~~ cluster_name = "" sql_user_name = "" 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.
Initialize the provider.
~~~ shell 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.
Create the Terraform plan. This shows the actions the provider will take, but won't perform them.
~~~ shell terraform plan ~~~
Create the cluster.
~~~ shell terraform apply ~~~
Enter yes when prompted to apply the plan and create the cluster.
(optional) Delete the cluster when you are done.
~~~ shell terraform destroy ~~~
Enter yes when prompted to delete the cluster.
Running this example will incur charges to your CockroachDB account. It defaults to a minimal hardware spec, but please remember to run
terraform destroywhen you're done if you don't need to keep your cluster.
In a terminal clone the terraform-provider-cockroach repository:
~~~ shell git clone https://github.com/cockroachdb/terraform-provider-cockroach.git ~~~
In a terminal go to the examples/workflows/cockroach_dedicated_cluster directory.
~~~ shell cd examples/workflows/cockroach_dedicated_cluster ~~~
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.
~~~ shell export COCKROACH_API_KEY= ~~~
Where <your API key> is the API key you copied from the CockroachDB Cloud Console.
In a text editor create a new file terraform.tfvars in cockroach_dedicated_cluster with the following settings.
~~~ cluster_name = "" database = "" sql_user_name = "" sql_user_password = "" cloud_provider = "" cloud_provider_regions = [""] cluster_node_count = num_virtual_cpus = storage_gib = allow_list_name = "" cidr_ip = "" cidr_prefix_length = os = "" ~~~
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').
Initialize the provider.
~~~ shell 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.
Create the Terraform plan. This shows the actions the provider will take, but won't perform them.
~~~ shell terraform plan ~~~
Create the cluster.
~~~ shell terraform apply ~~~
Enter yes when prompted to apply the plan and create the cluster.
(optional) Delete the cluster when you are done.
~~~ shell terraform destroy ~~~
Enter yes when prompted to delete the cluster.
$ claude mcp add terraform-provider-cockroach \
-- python -m otcore.mcp_server <graph>