Cloud Spanner with Terraform

1. Overview

Last Updated: 2020-07-23

What is Cloud Spanner?

Google Cloud Spanner is a globally distributed, ACID-compliant database that automatically handles replicas, sharding, and transaction processing, so you can quickly scale to meet any usage pattern and ensure success of your products.

Key Features

  • Relational database, built for scale: Everything you would expect from a relational database—schemas, SQL queries, and ACID transactions—battle tested and ready to scale globally.
  • 99.999% availability: Cloud Spanner delivers industry-leading 99.999% availability for multi-regional instances—10x less downtime than four nines—and provides transparent, synchronous replication across region and multi-region configurations.
  • Automatic sharding: Cloud Spanner optimizes performance by automatically sharding the data based on request load and size of the data. As a result, you can spend less time worrying about how to scale your database, and instead focus on scaling your business.

View all features

What you'll learn

  • How to use the Google Cloud Terraform provider.
  • Using Terraform to create Cloud Spanner instances and databases.
  • Using Terraform to modify Cloud Spanner resources.
  • Using Terraform to delete Cloud Spanner resources.

2. Setup and Requirements

Self-paced environment setup

If you don't already have a Google Account (Gmail or Google Apps), you must create one. Sign-in to Google Cloud Platform console ( console.cloud.google.com) and create a new project:

50983ac3fdbbf8d0.png

ea581205026ca8e3.png

Remember the project ID, a unique name across all Google Cloud projects (the name above has already been taken and will not work for you, sorry!). It will be referred to later in this codelab as PROJECT_ID.

Next, you'll need to enable billing in the Cloud Console in order to use Google Cloud resources.

Running through this codelab shouldn't cost you more than a few dollars, but it could be more if you decide to use more resources or if you leave them running (see "cleanup" section at the end of this document).

New users of Google Cloud Platform are eligible for a $300 free trial.

Authentication

If you haven't previously, please install the gcloud command line tool. Once gcloud is installed, active the Application Default Credentials by running the following command in your terminal:

$ gcloud auth application-default login

Terraform

If you haven't installed Terraform earlier, install Terraform.

3. Google Cloud Terraform Provider

Google Cloud Terraform Provider provides four Cloud Spanner resources:

In this codelab, we will create and manage Cloud Spanner instances and databases.

Environment

In your development environment, create a new directory for your Terraform configuration files.

$ mkdir ~/terraform-spanner
$ cd ~/terraform-spanner

Then, create a file named "main.tf" with the following content and replace PROJECT_ID wit h your own Google Cloud project ID:

$ cat >> main.tf <<'EOF'
provider "google" {
  project = "PROJECT_ID"
}
EOF

In this rest of this codelab, we are going to modify this file and apply changes.

4. Creating Instances and Databases

Modify the main.tf with the following content to add a new Cloud Spanner instance:

provider "google" {
  project = "PROJECT_ID"
}

resource "google_spanner_instance" "main" {
  config       = "regional-us-central1"
  display_name = "first-terraform-instance"
  num_nodes    = 3
}

Run the following command to apply the changes:

$ terraform apply
# ...
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
# ...
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

After the changes are applied, you will be able to see the instance at Google Cloud Console. Please note that regional configuration is not possible to modify after an instance is created.

48b67416982fa152.png

After creating the instance, we will create a database in the next steps. Modify main.tf with the following contents:

provider "google" {
  project = "PROJECT_ID"
}

resource "google_spanner_instance" "main" {
  config       = "regional-us-central1"
  display_name = "first-terraform-instance"
  num_nodes    = 3
}

resource "google_spanner_database" "database" {
  instance = google_spanner_instance.main.name
  name     = "my-first-database"
}

Again, use the following command to apply the changes:

$ terraform apply
# ...
Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

Upon success, my-first-database will be available under the instance:

9962a71c6b2a3aff.png

5. Modifying an Instance

As noted in the earlier section, not all properties of the instances are modifiable. But you can increase/decrease the number of nodes to adjust the resources used by the instance. The instance created had 3 nodes. By modifying the main.tf file, we are going to increase the number of nodes to 5:

provider "google" {
  project = "PROJECT_ID"
}

resource "google_spanner_instance" "main" {
  config       = "regional-us-central1"
  display_name = "first-terraform-instance"
  num_nodes    = 5
}

resource "google_spanner_database" "database" {
  instance = google_spanner_instance.main.name
  name     = "my-first-database"
}

The next step is to apply the changes:

$ terraform apply
# ...
Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

Once successful, the instance will be using 5 nodes.

6. Deleting a Database

You can delete a database permanently once you don't need it anymore. Simply, remove the database from main.tf and apply the changes.

provider "google" {
  project = "PROJECT_ID"
}

resource "google_spanner_instance" "main" {
  config       = "regional-us-central1"
  display_name = "first-terraform-instance"
  num_nodes    = 5
}

$ terraform apply
# ...
Apply complete! Resources: 0 added, 0 changed, 1 destroyed.

Once successful, the database will be permanently deleted.

7. Deleting an Instance

You can delete an instance permanently once you don't need it anymore. Simply, remove the instance from main.tf and apply the changes.

provider "google" {
  project = "PROJECT_ID"
}

$ terraform apply
# ...
Apply complete! Resources: 0 added, 0 changed, 1 destroyed.

Once successful, the instance will be permanently deleted.

8. Congratulations!

You have created, modified and deleted Cloud Spanner resources by using Terraform.

What we've covered

  • How to use the Google Cloud Terraform provider.
  • Using Terraform to create Cloud Spanner instances and databases.
  • Using Terraform to modify Cloud Spanner resources.
  • Using Terraform to delete Cloud Spanner resources.

Learn More