» Getting Started with the Google Provider

» Before you begin

  • Create a project in the Google Cloud Console and set up billing on that project. Any examples in this guide will be part of the GCP "always free" tier.
  • Install Terraform and read the Terraform getting started guide that follows. This guide will assume basic proficiency with Terraform - it is an introduction to the Google provider.

» Configuring the Provider

First, authenticate with GCP. The easiest way to do this is to run gcloud auth application-default login, if you already have gcloud installed. If you don't already have it, gcloud can be installed with apt-get install google-cloud-sdk on Debian-based machines. For a production use-case, you will want to use service account authentication, which you can learn about further down in this doc, but for experimenting, gcloud authentication will work fine.

Next, create a Terraform config file named "main.tf". Inside, you'll want to include the following configuration:

provider "google" {
  project = "{{YOUR GCP PROJECT}}"
  region  = "us-central1"
  zone    = "us-central1-c"
}
  • The project field should be your personal project id. The project indicates the default GCP project all of your resources will be created in. Most Terraform resources will have a project field.
  • The region and zone are locations for your resources to be created in.
    • The region will be used to choose the default location for regional resources. Regional resources are spread across several zones.
    • The zone will be used to choose the default location for zonal resources. Zonal resources exist in a single zone. All zones are a part of a region.

Not all resources require a location. Some GCP resources are global and are automatically spread across all of GCP.

» Creating a VM instance

A Google Compute Engine VM instance is named google_compute_instance in Terraform. The google part of the name identifies the provider for Terraform, compute indicates the GCP product family, and instance is the resource name.

Google provider resources will generally, although not always, be named after the name used in gcloud/the REST API. For example, a VM instance is called instance in the API. Most resource field names will also correspond 1:1 with their gcloud/REST API names.

If you look at the google_compute_instance documentation, you'll see that project and zone (VM instances are a zonal resource) are listed as optional. When present in a resource's config block, these values will be used. If omitted, the provider defaults will be used instead.

Add the following to your config file:

resource "google_compute_instance" "vm_instance" {
  name         = "terraform-instance"
  machine_type = "f1-micro"

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-9"
    }
  }

  network_interface {
    # A default network is created for all GCP projects
    network = "default"
    access_config {
    }
  }
}

» Linking GCP resources

Like this VM instance, nearly every GCP resource will have a name field. They are used as a short way to identify resources, and a resource's display name in the Cloud Console will be the one defined in the name field.

When linking resources in a Terraform config though, you'll primarily want to use a different field, the self_link of a resource. Like name, nearly every resource has a self_link. They look like:

{{API base url}}/projects/{{your project}}/{{location type}}/{{location}}/{{resource type}}/{{name}}

For example, the instance defined earlier in a project named foo will have the self_link:

https://www.googleapis.com/compute/v1/projects/foo/zones/us-central1-c/instances/terraform-instance

A resource's self_link is a unique reference to that resource. When linking two resources in Terraform, you can use Terraform interpolation to avoid typing out the self link! Let's use a google_compute_network to demonstrate.

Add this block to your config:

resource "google_compute_network" "vpc_network" {
  name                    = "terraform-network"
  auto_create_subnetworks = "true"
}

This will create VPC network resource with a subnetwork in each region. Next, change the network of the google_compute_instance from the "default" network to the new network.

network_interface {
-  # A default network is created for all GCP projects
-  network = "default"
+  network = google_compute_network.vpc_network.self_link
  access_config {

This means that when we create the VM instance, it will use "terraform-network" instead of the default VPC network for the project. If you run terraform plan, you will see that "terraform-instance" depends on "terraform-network".

Your configuration is complete. Before you can run terraform apply though, Terraform needs GCP credentials.

» Adding credentials

In order to make requests against the GCP API, you need to authenticate to prove that it's you making the request. The preferred method of provisioning resources with Terraform is to use a GCP service account, a "robot account" that can be granted a limited set of IAM permissions.

From the service account key page in the Cloud Console choose an existing account, or create a new one. Next, download the JSON key file. Name it something you can remember, and store it somewhere secure on your machine.

Note: Currently the only supported service account credentials are credentials downloaded from Cloud Console or generated by gcloud.

You supply the key to Terraform using the environment variable GOOGLE_APPLICATION_CREDENTIALS, setting the value to the location of the file.

export GOOGLE_APPLICATION_CREDENTIALS={{path}}

If you choose to use gcloud-generated credentials, and you encounter quota or billing issues which don't seem to apply to you, you may want to set user_project_override to true in the provider block - see the provider reference for more information.

» Provisioning your resources

By now, your config will look something like:

provider "google" {
  project = "{{YOUR GCP PROJECT}}"
  region  = "us-central1"
  zone    = "us-central1-c"
}

resource "google_compute_instance" "vm_instance" {
  name         = "terraform-instance"
  machine_type = "f1-micro"

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-9"
    }
  }

  network_interface {
    # A default network is created for all GCP projects
    network = google_compute_network.vpc_network.self_link
    access_config {
    }
  }
}

resource "google_compute_network" "vpc_network" {
  name                    = "terraform-network"
  auto_create_subnetworks = "true"
}

With a Terraform config and with your credentials configured, it's time to provision your resources:

terraform apply

Congratulations! You've gotten started using the Google provider and provisioned a virtual machine on Google Cloud Platform. The key concepts unique to GCP are:

  • How a project contains resources
    • and how to use a default project in your provider
  • What a resource being global, regional, or zonal means on GCP
    • and how to specify a default region and zone
  • How GCP uses name and self_link to identify resources
  • How to add GCP service account credentials to Terraform

Run terraform destroy to tear down your resources.

Afterwards, check out the provider reference for more details on configuring the provider block (including how you can eliminate it entirely!).

You can also check out the GCP Community tutorials such as: