title | summary |
---|---|
Use Cluster Resource |
Learn how to use the cluster resource to create and modify a TiDB Cloud cluster. |
You can learn how to manage a TiDB Cloud cluster with the tidbcloud_cluster
resource in this document.
In addition, you will also learn how to get the necessary information with the tidbcloud_projects
and tidbcloud_cluster_specs
data sources.
The features of the tidbcloud_cluster
resource include the following:
- Create TiDB Cloud Serverless and TiDB Cloud Dedicated clusters.
- Modify TiDB Cloud Dedicated clusters.
- Delete TiDB Cloud Serverless and TiDB Cloud Dedicated clusters.
Each TiDB cluster is in a project. Before you create a TiDB cluster, you need to get the ID of the project in which you want to create a cluster.
To view the information of all available projects, you can use the tidbcloud_projects
data source as follows:
-
In the
main.tf
file that is created when you Get TiDB Cloud Terraform Provider, add thedata
andoutput
blocks as follows:terraform { required_providers { tidbcloud = { source = "tidbcloud/tidbcloud" } } } provider "tidbcloud" { public_key = "your_public_key" private_key = "your_private_key" sync = true } data "tidbcloud_projects" "example_project" { page = 1 page_size = 10 } output "projects" { value = data.tidbcloud_projects.example_project.items }
-
Use the
data
block to define the data source of TiDB Cloud, including the data source type and the data source name.- To use the projects data source, set the data source type as
tidbcloud_projects
. - For the data source name, you can define it according to your need. For example, "example_project".
- For the
tidbcloud_projects
data source, you can use thepage
andpage_size
attributes to limit the maximum number of projects you want to check.
- To use the projects data source, set the data source type as
-
Use the
output
block to define the data source information to be displayed in the output, and expose the information for other Terraform configurations to use.The
output
block works similarly to returned values in programming languages. See Terraform documentation for more details.
To get all the available configurations for the resources and data sources, see this configuration documentation.
-
-
Run the
terraform apply
command to apply the configurations. You need to typeyes
at the confirmation prompt to proceed.To skip the prompt, use
terraform apply --auto-approve
:$ terraform apply --auto-approve Changes to Outputs: + projects = [ + { + cluster_count = 0 + create_timestamp = "1649154426" + id = "1372813089191121286" + name = "test1" + org_id = "1372813089189921287" + user_count = 1 }, + { + cluster_count = 1 + create_timestamp = "1640602740" + id = "1372813089189561287" + name = "default project" + org_id = "1372813089189921287" + user_count = 1 }, ] You can apply this plan to save these new output values to the Terraform state, without changing any real infrastructure. Apply complete! Resources: 0 added, 0 changed, 0 destroyed. Outputs: projects = tolist([ { "cluster_count" = 0 "create_timestamp" = "1649154426" "id" = "1372813089191121286" "name" = "test1" "org_id" = "1372813089189921287" "user_count" = 1 }, { "cluster_count" = 1 "create_timestamp" = "1640602740" "id" = "1372813089189561287" "name" = "default project" "org_id" = "1372813089189921287" "user_count" = 1 }, ])
Now, you can get all the available projects from the output. Copy one of the project IDs that you need.
Before you create a cluster, you need to get the cluster specification information, which contains all available configuration values (such as supported cloud providers, regions, and node sizes).
To get the cluster specification information, you can use the tidbcloud_cluster_specs
data source as follows:
-
Edit the
main.tf
file as follows:terraform { required_providers { tidbcloud = { source = "tidbcloud/tidbcloud" } } } provider "tidbcloud" { public_key = "your_public_key" private_key = "your_private_key" sync = true } data "tidbcloud_cluster_specs" "example_cluster_spec" { } output "cluster_spec" { value = data.tidbcloud_cluster_specs.example_cluster_spec.items }
-
Run the
terraform apply --auto-approve
command and you will get the cluster specification information.Click the following line to get a part of the example results for your reference.
Cluster specification
{ "cloud_provider" = "AWS" "cluster_type" = "DEDICATED" "region" = "eu-central-1" "tidb" = tolist([ { "node_quantity_range" = { "min" = 1 "step" = 1 } "node_size" = "4C16G" }, { "node_quantity_range" = { "min" = 1 "step" = 1 } "node_size" = "8C16G" }, { "node_quantity_range" = { "min" = 1 "step" = 1 } "node_size" = "16C32G" }, ]) "tiflash" = tolist([ { "node_quantity_range" = { "min" = 0 "step" = 1 } "node_size" = "8C64G" "storage_size_gib_range" = { "max" = 2048 "min" = 500 } }, { "node_quantity_range" = { "min" = 0 "step" = 1 } "node_size" = "16C128G" "storage_size_gib_range" = { "max" = 2048 "min" = 500 } }, ]) "tikv" = tolist([ { "node_quantity_range" = { "min" = 3 "step" = 3 } "node_size" = "4C16G" "storage_size_gib_range" = { "max" = 2048 "min" = 200 } }, { "node_quantity_range" = { "min" = 3 "step" = 3 } "node_size" = "8C32G" "storage_size_gib_range" = { "max" = 4096 "min" = 500 } }, { "node_quantity_range" = { "min" = 3 "step" = 3 } "node_size" = "8C64G" "storage_size_gib_range" = { "max" = 4096 "min" = 500 } }, { "node_quantity_range" = { "min" = 3 "step" = 3 } "node_size" = "16C64G" "storage_size_gib_range" = { "max" = 4096 "min" = 500 } }, ]) }
In the results:
cloud_provider
is the cloud provider on which a TiDB cluster can be hosted.region
is the region ofcloud_provider
.node_quantity_range
shows the minimum node number and the step to scale a node.node_size
is the size of a node.storage_size_gib_range
shows the minimum and maximum storage size you can set for a node.
Note:
Before you begin, make sure that you have set a CIDR in the TiDB Cloud console. For more information, see Set a CIDR.
You can create a cluster using the tidbcloud_cluster
resource.
The following example shows how to create a TiDB Cloud Dedicated cluster.
-
Create a directory for the cluster and enter it.
-
Create a
cluster.tf
file:terraform { required_providers { tidbcloud = { source = "tidbcloud/tidbcloud" } } } provider "tidbcloud" { public_key = "your_public_key" private_key = "your_private_key" sync = true } resource "tidbcloud_cluster" "example_cluster" { project_id = "1372813089189561287" name = "firstCluster" cluster_type = "DEDICATED" cloud_provider = "AWS" region = "eu-central-1" config = { root_password = "Your_root_password1." port = 4000 components = { tidb = { node_size : "8C16G" node_quantity : 1 } tikv = { node_size : "8C32G" storage_size_gib : 500, node_quantity : 3 } } } }
Use the
resource
block to define the resource of TiDB Cloud, including the resource type, resource name, and resource details.- To use the cluster resource, set the resource type as
tidbcloud_cluster
. - For the resource name, you can define it according to your need. For example,
example_cluster
. - For the resource details, you can configure them according to the Project ID and the cluster specification information.
- To use the cluster resource, set the resource type as
-
Run the
terraform apply
command. It is not recommended to useterraform apply --auto-approve
when you apply a resource.$ terraform apply Terraform will perform the following actions: # tidbcloud_cluster.example_cluster will be created + resource "tidbcloud_cluster" "example_cluster" { + cloud_provider = "AWS" + cluster_type = "DEDICATED" + config = { + components = { + tidb = { + node_quantity = 1 + node_size = "8C16G" } + tikv = { + node_quantity = 3 + node_size = "8C32G" + storage_size_gib = 500 } } + ip_access_list = [ + { + cidr = "0.0.0.0/0" + description = "all" }, ] + port = 4000 + root_password = "Your_root_password1." } + id = (known after apply) + name = "firstCluster" + project_id = "1372813089189561287" + region = "eu-central-1" + status = (known after apply) } Plan: 1 to add, 0 to change, 0 to destroy. Do you want to perform these actions? Terraform will perform the actions described above. Only 'yes' will be accepted to approve. Enter a value:
As in the above result, Terraform generates an execution plan for you, which describes the actions Terraform will take:
- You can check the difference between the configurations and the states.
- You can also see the results of this
apply
. It will add a new resource, and no resource will be changed or destroyed. - The
known after apply
shows that you will get the value afterapply
.
-
If everything in your plan looks fine, type
yes
to continue:Do you want to perform these actions? Terraform will perform the actions described above. Only 'yes' will be accepted to approve. Enter a value: yes tidbcloud_cluster.example_cluster: Creating... tidbcloud_cluster.example_cluster: Creation complete after 1s [id=1379661944630234067] Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
-
Use the
terraform show
orterraform state show tidbcloud_cluster.${resource-name}
command to inspect the state of your resource. The former will show the states of all resources and data sources.$ terraform state show tidbcloud_cluster.example_cluster # tidbcloud_cluster.example_cluster: resource "tidbcloud_cluster" "example_cluster" { cloud_provider = "AWS" cluster_type = "DEDICATED" config = { components = { tidb = { node_quantity = 1 node_size = "8C16G" } tikv = { node_quantity = 3 node_size = "8C32G" storage_size_gib = 500 } } ip_access_list = [ # (1 unchanged element hidden) ] port = 4000 root_password = "Your_root_password1." } id = "1379661944630234067" name = "firstCluster" project_id = "1372813089189561287" region = "eu-central-1" status = "CREATING" }
The status of the cluster is
CREATING
. In this case, you need to wait until it changes toAVAILABLE
, which usually takes 10 minutes at least. -
If you want to check the latest status, run the
terraform refresh
command to update the state, and then run theterraform state show tidbcloud_cluster.${resource-name}
command to display the state.$ terraform refresh tidbcloud_cluster.example_cluster: Refreshing state... [id=1379661944630234067] $ terraform state show tidbcloud_cluster.example_cluste # tidbcloud_cluster.example_cluster: resource "tidbcloud_cluster" "example_cluster" { cloud_provider = "AWS" cluster_type = "DEDICATED" config = { components = { tidb = { node_quantity = 1 node_size = "8C16G" } tikv = { node_quantity = 3 node_size = "8C32G" storage_size_gib = 500 } } ip_access_list = [ # (1 unchanged element hidden) ] port = 4000 root_password = "Your_root_password1." } id = "1379661944630234067" name = "firstCluster" project_id = "1372813089189561287" region = "eu-central-1" status = "AVAILABLE" }
When the status is AVAILABLE
, it indicates that your TiDB cluster is created and ready for use.
For a TiDB Cloud Dedicated cluster, you can use Terraform to manage cluster resources as follows:
- Add a TiFlash component to the cluster.
- Scale the cluster.
- Pause or resume the cluster.
-
In the
cluster.tf
file that is used when you create the cluster, add thetiflash
configurations to thecomponents
field.For example:
components = { tidb = { node_size : "8C16G" node_quantity : 1 } tikv = { node_size : "8C32G" storage_size_gib : 500 node_quantity : 3 } tiflash = { node_size : "8C64G" storage_size_gib : 500 node_quantity : 1 } }
-
Run the
terraform apply
command:$ terraform apply tidbcloud_cluster.example_cluster: Refreshing state... [id=1379661944630234067] Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: ~ update in-place Terraform will perform the following actions: # tidbcloud_cluster.example_cluster will be updated in-place ~ resource "tidbcloud_cluster" "example_cluster" { ~ config = { ~ components = { + tiflash = { + node_quantity = 1 + node_size = "8C64G" + storage_size_gib = 500 } # (2 unchanged attributes hidden) } # (3 unchanged attributes hidden) } id = "1379661944630234067" name = "firstCluster" ~ status = "AVAILABLE" -> (known after apply) # (4 unchanged attributes hidden) } Plan: 0 to add, 1 to change, 0 to destroy. Do you want to perform these actions? Terraform will perform the actions described above. Only 'yes' will be accepted to approve. Enter a value:
As in the above execution plan, TiFlash will be added, and one resource will be changed.
-
If everything in your plan looks fine, type
yes
to continue:Enter a value: yes tidbcloud_cluster.example_cluster: Modifying... [id=1379661944630234067] tidbcloud_cluster.example_cluster: Modifications complete after 2s [id=1379661944630234067] Apply complete! Resources: 0 added, 1 changed, 0 destroyed.
-
Use
terraform state show tidbcloud_cluster.${resource-name}
to see the status:$ terraform state show tidbcloud_cluster.example_cluster # tidbcloud_cluster.example_cluster: resource "tidbcloud_cluster" "example_cluster" { cloud_provider = "AWS" cluster_type = "DEDICATED" config = { components = { tidb = { node_quantity = 1 node_size = "8C16G" } tiflash = { node_quantity = 1 node_size = "8C64G" storage_size_gib = 500 } tikv = { node_quantity = 3 node_size = "8C32G" storage_size_gib = 500 } } ip_access_list = [ # (1 unchanged element hidden) ] port = 4000 root_password = "Your_root_password1." } id = "1379661944630234067" name = "firstCluster" project_id = "1372813089189561287" region = "eu-central-1" status = "MODIFYING" }
The MODIFYING
status indicates that the cluster is changing now. Wait for a moment. The status will be changed to AVAILABLE
.
You can scale a TiDB cluster when its status is AVAILABLE
.
-
In the
cluster.tf
file that is used when you create the cluster, edit thecomponents
configurations.For example, to add one more node for TiDB, 3 more nodes for TiKV (The number of TiKV nodes needs to be a multiple of 3 for its step is 3. You can get this information from the cluster specification), and one more node for TiFlash, you can edit the configurations as follows:
components = { tidb = { node_size : "8C16G" node_quantity : 2 } tikv = { node_size : "8C32G" storage_size_gib : 500 node_quantity : 6 } tiflash = { node_size : "8C64G" storage_size_gib : 500 node_quantity : 2 } }
-
Run the
terraform apply
command and typeyes
for confirmation:$ terraform apply tidbcloud_cluster.example_cluster: Refreshing state... [id=1379661944630234067] Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: ~ update in-place Terraform will perform the following actions: # tidbcloud_cluster.example_cluster will be updated in-place ~ resource "tidbcloud_cluster" "example_cluster" { ~ config = { ~ components = { ~ tidb = { ~ node_quantity = 1 -> 2 # (1 unchanged attribute hidden) } ~ tiflash = { ~ node_quantity = 1 -> 2 # (2 unchanged attributes hidden) } ~ tikv = { ~ node_quantity = 3 -> 6 # (2 unchanged attributes hidden) } } # (3 unchanged attributes hidden) } id = "1379661944630234067" name = "firstCluster" ~ status = "AVAILABLE" -> (known after apply) # (4 unchanged attributes hidden) } Plan: 0 to add, 1 to change, 0 to destroy. Do you want to perform these actions? Terraform will perform the actions described above. Only 'yes' will be accepted to approve. Enter a value: yes tidbcloud_cluster.example_cluster: Modifying... [id=1379661944630234067] tidbcloud_cluster.example_cluster: Modifications complete after 2s [id=1379661944630234067] Apply complete! Resources: 0 added, 1 changed, 0 destroyed.
Wait for the status to turn from MODIFYING
to AVAILABLE
.
You can pause a cluster when its status is AVAILABLE
or resume a cluster when its status is PAUSED
.
- Set
paused = true
to pause a cluster. - Set
paused = false
to resume a cluster.
-
In the
cluster.tf
file that is used when you create the cluster, addpause = true
to theconfig
configurations:config = { paused = true root_password = "Your_root_password1." port = 4000 ... }
-
Run the
terraform apply
command and typeyes
after check:$ terraform apply tidbcloud_cluster.example_cluster: Refreshing state... [id=1379661944630234067] Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: ~ update in-place Terraform will perform the following actions: # tidbcloud_cluster.example_cluster will be updated in-place ~ resource "tidbcloud_cluster" "example_cluster" { ~ config = { + paused = true # (4 unchanged attributes hidden) } id = "1379661944630234067" name = "firstCluster" ~ status = "AVAILABLE" -> (known after apply) # (4 unchanged attributes hidden) } Plan: 0 to add, 1 to change, 0 to destroy. Do you want to perform these actions? Terraform will perform the actions described above. Only 'yes' will be accepted to approve. Enter a value: yes tidbcloud_cluster.example_cluster: Modifying... [id=1379661944630234067] tidbcloud_cluster.example_cluster: Modifications complete after 2s [id=1379661944630234067] Apply complete! Resources: 0 added, 1 changed, 0 destroyed.
-
Use the
terraform state show tidbcloud_cluster.${resource-name}
command to check the status:$ terraform state show tidbcloud_cluster.example_cluster # tidbcloud_cluster.example_cluster: resource "tidbcloud_cluster" "example_cluster" { cloud_provider = "AWS" cluster_type = "DEDICATED" config = { components = { tidb = { node_quantity = 2 node_size = "8C16G" } tiflash = { node_quantity = 2 node_size = "8C64G" storage_size_gib = 500 } tikv = { node_quantity = 6 node_size = "8C32G" storage_size_gib = 500 } } ip_access_list = [ # (1 unchanged element hidden) ] paused = true port = 4000 root_password = "Your_root_password1." } id = "1379661944630234067" name = "firstCluster" project_id = "1372813089189561287" region = "eu-central-1" status = "PAUSED" }
-
When you need to resume the cluster, set
paused = false
:config = { paused = false root_password = "Your_root_password1." port = 4000 ... }
-
Run the
terraform apply
command and typeyes
for confirmation. If you use theterraform state show tidbcloud_cluster.${resource-name}
command to check the status, you will find it turns toRESUMING
:# tidbcloud_cluster.example_cluster: resource "tidbcloud_cluster" "example_cluster" { cloud_provider = "AWS" cluster_type = "DEDICATED" config = { components = { tidb = { node_quantity = 2 node_size = "8C16G" } tiflash = { node_quantity = 2 node_size = "8C64G" storage_size_gib = 500 } tikv = { node_quantity = 6 node_size = "8C32G" storage_size_gib = 500 } } ip_access_list = [ # (1 unchanged element hidden) ] paused = false port = 4000 root_password = "Your_root_password1." } id = "1379661944630234067" name = "firstCluster" project_id = "1372813089189561287" region = "eu-central-1" status = "RESUMING" }
-
Wait for a moment, then use the
terraform refersh
command to update the state. The status will be changed toAVAILABLE
finally.
Now, you have created and managed a TiDB Cloud Dedicated cluster with Terraform. Next, you can try creating a backup of the cluster by our backup resource.
For a TiDB cluster that is not managed by Terraform, you can use Terraform to manage it just by importing it.
For example, you can import a cluster that is not created by Terraform or import a cluster that is created with the restore resource.
-
Create a
import_cluster.tf
file as follows:terraform { required_providers { tidbcloud = { source = "tidbcloud/tidbcloud" } } } resource "tidbcloud_cluster" "import_cluster" {}
-
Import the cluster by
terraform import tidbcloud_cluster.import_cluster projectId,clusterId
:For example:
$ terraform import tidbcloud_cluster.import_cluster 1372813089189561287,1379661944630264072 tidbcloud_cluster.import_cluster: Importing from ID "1372813089189561287,1379661944630264072"... tidbcloud_cluster.import_cluster: Import prepared! Prepared tidbcloud_cluster for import tidbcloud_cluster.import_cluster: Refreshing state... [id=1379661944630264072] Import successful! The resources that were imported are shown above. These resources are now in your Terraform state and will henceforth be managed by Terraform.
-
Run the
terraform state show tidbcloud_cluster.import_cluster
command to check the status of the cluster:$ terraform state show tidbcloud_cluster.import_cluster # tidbcloud_cluster.import_cluster: resource "tidbcloud_cluster" "import_cluster" { cloud_provider = "AWS" cluster_type = "DEDICATED" config = { components = { tidb = { node_quantity = 2 node_size = "8C16G" } tiflash = { node_quantity = 2 node_size = "8C64G" storage_size_gib = 500 } tikv = { node_quantity = 6 node_size = "8C32G" storage_size_gib = 500 } } port = 4000 } id = "1379661944630264072" name = "restoreCluster" project_id = "1372813089189561287" region = "eu-central-1" status = "AVAILABLE" }
-
To manage the cluster using Terraform, you can copy the output of the previous step to your configuration file. Note that you need to delete the lines of
id
andstatus
, because they will be controlled by Terraform instead:resource "tidbcloud_cluster" "import_cluster" { cloud_provider = "AWS" cluster_type = "DEDICATED" config = { components = { tidb = { node_quantity = 2 node_size = "8C16G" } tiflash = { node_quantity = 2 node_size = "8C64G" storage_size_gib = 500 } tikv = { node_quantity = 6 node_size = "8C32G" storage_size_gib = 500 } } port = 4000 } name = "restoreCluster" project_id = "1372813089189561287" region = "eu-central-1" }
-
You can use
terraform fmt
to format your configuration file:$ terraform fmt
-
To ensure the consistency of the configuration and state, you can execute
terraform plan
orterraform apply
. If you seeNo changes
, the import is successful.$ terraform apply tidbcloud_cluster.import_cluster: Refreshing state... [id=1379661944630264072] No changes. Your infrastructure matches the configuration. Terraform has compared your real infrastructure against your configuration and found no differences, so no changes are needed. Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
Now you can use Terraform to manage the cluster.
To delete a cluster, go to the cluster directory where the corresponding cluster.tf
file is located, and then run the terraform destroy
command to destroy the cluster resource:
$ terraform destroy
Plan: 0 to add, 0 to change, 1 to destroy.
Do you really want to destroy all resources?
Terraform will destroy all your managed infrastructure, as shown above.
There is no undo. Only 'yes' will be accepted to confirm.
Enter a value: yes
Now, if you run the terraform show
command, you will get nothing because the resource has been cleared:
$ terraform show