https://github.com/cockroachdb/terraform-provider-cockroach
Terraform provider for CockroachDB Cloud
https://github.com/cockroachdb/terraform-provider-cockroach
Last synced: 9 days ago
JSON representation
Terraform provider for CockroachDB Cloud
- Host: GitHub
- URL: https://github.com/cockroachdb/terraform-provider-cockroach
- Owner: cockroachdb
- License: apache-2.0
- Created: 2022-03-09T14:26:40.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-06-13T12:43:50.000Z (13 days ago)
- Last Synced: 2025-06-13T14:02:36.364Z (13 days ago)
- Language: Go
- Homepage:
- Size: 10.6 MB
- Stars: 58
- Watchers: 47
- Forks: 14
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Terraform provider for CockroachDB Cloud
[`terraform-provider-cockroach`](https://registry.terraform.io/providers/cockroachdb/cockroach/latest) is the [Terraform provider](https://learn.hashicorp.com/collections/terraform/providers) for the CockroachDB Cloud API [[reference](https://www.cockroachlabs.com/docs/api/cloud/v1), [getting started](https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api)].
- [Provision a CockroachDB Cloud Cluster with Terraform](https://www.cockroachlabs.com/docs/cockroachcloud/provision-a-cluster-with-terraform.html)
- [More information about CockroachDB](https://www.cockroachlabs.com/)
- [More information about Terraform](https://terraform.io)
For information on developing `terraform-provider-cockroach` see [DEVELOPMENT.md](DEVELOPMENT.md).
## Get Started
### _Warning_: Use of *private endpoints* requires >=v1.7.6
If you intend to use this provider to provision [private endpoints](https://github.com/cockroachdb/terraform-provider-cockroach/blob/main/docs/resources/private_endpoint_connection.md):
- [AWS PrivateLink](https://www.cockroachlabs.com/docs/cockroachcloud/aws-privatelink)
- [GCP Private Service Connect](https://www.cockroachlabs.com/docs/cockroachcloud/connect-to-your-cluster#gcp-private-service-connect)
- [Azure Private Link](https://www.cockroachlabs.com/docs/cockroachcloud/cockroachdb-dedicated-on-azure)
You must install/upgrade to [version 1.7.6](https://github.com/cockroachdb/terraform-provider-cockroach/releases/tag/v1.7.6) or [later](https://registry.terraform.io/providers/cockroachdb/cockroach/latest).
### Prerequisites
Before you use `terraform-provider-cockroach` you must [install Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli) and [`git`](https://git-scm.com/downloads) on your local machine.
## Run the Serverless Example
1. In a terminal clone the `terraform-provider-cockroach` repository:
~~~ shell
git clone https://github.com/cockroachdb/terraform-provider-cockroach.git
~~~
1. Go to the `examples/workflows/cockroach_serverless_cluster` directory.
~~~ shell
cd examples/workflows/cockroach_serverless_cluster
~~~
1. The provider requires an API key set in an environment variable named `COCKROACH_API_KEY`. Copy the [API key](https://www.cockroachlabs.com/docs/cockroachcloud/console-access-management.html#api-access) from the CockroachDB Cloud console and create the `COCKROACH_API_KEY` environment variable.
~~~ shell
export COCKROACH_API_KEY=
~~~
Where `` is the API key you copied from the CockroachDB Cloud Console.
1. 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:
- `` is the name of the cluster you want to create.
- `` is the name of the SQL user you want to create.
- `` is the password for the SQL user you want to create.
1. 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.
1. Create the Terraform plan. This shows the actions the provider will take, but won't perform them.
~~~ shell
terraform plan
~~~
1. Create the cluster.
~~~ shell
terraform apply
~~~
Enter `yes` when prompted to apply the plan and create the cluster.
1. (optional) Delete the cluster when you are done.
~~~ shell
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:
~~~ shell
git clone https://github.com/cockroachdb/terraform-provider-cockroach.git
~~~
1. In a terminal go to the `examples/workflows/cockroach_dedicated_cluster` directory.
~~~ shell
cd examples/workflows/cockroach_dedicated_cluster
~~~
1. The provider requires an API key set in an environment variable named `COCKROACH_API_KEY`. Copy the [API key](https://www.cockroachlabs.com/docs/cockroachcloud/console-access-management.html#api-access) from the CockroachDB Cloud console and create the `COCKROACH_API_KEY` environment variable.
~~~ shell
export COCKROACH_API_KEY=
~~~
Where `` is the API key you copied from the CockroachDB Cloud Console.
1. 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:
- `` is the name of the cluster you want to create.
- `` 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.
- `` is the name of the SQL user you want to create.
- `` is the password for the SQL user you want to create.
- `` is the cloud infrastructure provider. Possible values are `GCP` or `AWS` or `AZURE`.
- `` is the region code or codes for the cloud infrastructure provider. For multi-region clusters, separate each region with a comma.
- `` 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.
- `` 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](https://www.cockroachlabs.com/docs/cockroachcloud/create-your-cluster#step-5-configure-cluster-capacity).
- `` is the amount of storage specified in GiB.
- `` 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")
- `` is the Classless Inter-Domain Routing (CIDR) IP address base. (i.e. 123.123.123.123)
- `` 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.
- `` is the name of the OS that will be used to connect from for connection string output. Possible values are ('WINDOWS', 'MAC', and 'LINUX').
1. 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.
1. Create the Terraform plan. This shows the actions the provider will take, but won't perform them.
~~~ shell
terraform plan
~~~
1. Create the cluster.
~~~ shell
terraform apply
~~~
Enter `yes` when prompted to apply the plan and create the cluster.
1. (optional) Delete the cluster when you are done.
~~~ shell
terraform destroy
~~~
Enter `yes` when prompted to delete the cluster.