terraform-provider-google/website/docs/getting_started.html.markdown

layout	page_title	sidebar_current	description
google	Getting Started with the Google provider	docs-google-provider-getting-started	Getting started with the Google Cloud Platform provider

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 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.

-> Want to try out another location? Check out the list of available regions and zones. Instances created in zones outside the US are not part of the always free tier and could incur charges.

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 = {
    }
  }
}

~> Note: Don't use terraform apply quite yet! You still need to add GCP credentials. If you want to try out provisioning your VM instance before continuing, follow the instructions in the "Adding credentials" section below.

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.

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

export GOOGLE_CLOUD_KEYFILE_JSON={{path}}

-> Remember to add this line to a startup file such as bash_profile or bashrc to store your credentials across sessions!

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:

• Getting started with Terraform on Google Cloud Platform

• Managing GCP Projects with Terraform

• Modular Load Balancing with Terraform