v5.18.0/website/docs/guides/getting_started.html.markdown - terraform-provider-google-beta - Git at Google

 ---
 page_title: "Getting Started with the Google provider"
 description: |-
   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](https://console.cloud.google.com/)
 and set up billing on that project. Any examples in this guide will be part of
 the [GCP "always free" tier](https://cloud.google.com/free/).
 * [Install Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli?in=terraform/gcp-get-started)
 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, you can install it from [here](https://cloud.google.com/sdk/docs/install).

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

 ```hcl
 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](https://cloud.google.com/compute/docs/regions-zones/global-regional-zonal-resources)
 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](https://cloud.google.com/compute/docs/regions-zones/#available).
 Instances created in zones outside the US are not necessarily part of the always free tier
 and could incur charges.

 ## Creating a VM instance
 A [Google Compute Engine VM instance](https://cloud.google.com/compute/docs/instances/) 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](https://cloud.google.com/compute/docs/reference/rest/v1/instances).
 Most resource field names will also correspond 1:1 with their `gcloud`/REST API
 names.

 If you look at the [`google_compute_instance documentation`](/docs/providers/google/r/compute_instance.html),
 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:

 ```hcl
 resource "google_compute_instance" "vm_instance" {
   name         = "terraform-instance"
   machine_type = "e2-micro"

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

   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:

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

 This will create [VPC network resource](/docs/providers/google/r/compute_network.html)
 with a subnetwork in each region. Next, change the network of the
 `google_compute_instance` from the `"default"` network to the new network.

 ```diff
 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 on your workstation is to use the Google Cloud SDK as we mentioned earlier.

 You can also use a Google Cloud Service Account with terraform.

 From [the service account key page in the Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts)
 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.

 ```bash
 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](/docs/providers/google/guides/provider_reference.html) for more information.

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

 ### Using Terraform Cloud as the Backend
 You need to use a different [environment variable](https://www.terraform.io/docs/cloud/workspaces/variables.html) name to store your credentials in Terraform Cloud.
 1. Create an environment variable called `GOOGLE_CREDENTIALS` in your Terraform Cloud workspace.
 2. Remove the newline characters from your JSON key file and then paste the credentials into the environment variable value field. (Running `cat CREDENTIALS.json | tr -s '\n' ' '` will remove newline characters from your JSON key file)
 3. Mark the variable as **Sensitive** and click **Save variable**.

 All runs within the workspace will use the `GOOGLE_CREDENTIALS` variable to authenticate with Google Cloud Platform.

 ~> **Note:** When running inside a CLI-driven TFC workspace, local environment variables will only be accessible when executed [locally](https://www.terraform.io/cloud-docs/workspaces/settings#execution-mode). All credentials environment variables (including default application credentials) need to be set in the [Variables tab](https://www.terraform.io/cloud-docs/workspaces/variables/managing-variables#workspace-specific-variables) in order to be accessible by workspaces executed remotely.

 ## Provisioning your resources
 By now, your config will look something like:

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

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

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

   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:

 ```hcl
 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](/docs/providers/google/guides/provider_reference.html) for more details on configuring
 the provider block (including how you can eliminate it entirely!).

 You can also check out the [GCP Community tutorials](https://cloud.google.com/community/tutorials/)
 such as:

 * [Getting started with Terraform on Google Cloud Platform](https://cloud.google.com/community/tutorials/getting-started-on-gcp-with-terraform)

 * [Managing GCP Projects with Terraform](https://cloud.google.com/community/tutorials/managing-gcp-projects-with-terraform)

 * [Modular Load Balancing with Terraform](https://cloud.google.com/community/tutorials/modular-load-balancing-with-terraform)
	---
	page_title: "Getting Started with the Google provider"
	description: \|-
	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](https://console.cloud.google.com/)
	and set up billing on that project. Any examples in this guide will be part of
	the [GCP "always free" tier](https://cloud.google.com/free/).
	* [Install Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli?in=terraform/gcp-get-started)
	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, you can install it from [here](https://cloud.google.com/sdk/docs/install).

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

	```hcl
	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](https://cloud.google.com/compute/docs/regions-zones/global-regional-zonal-resources)
	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](https://cloud.google.com/compute/docs/regions-zones/#available).
	Instances created in zones outside the US are not necessarily part of the always free tier
	and could incur charges.

	## Creating a VM instance
	A [Google Compute Engine VM instance](https://cloud.google.com/compute/docs/instances/) 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](https://cloud.google.com/compute/docs/reference/rest/v1/instances).
	Most resource field names will also correspond 1:1 with their `gcloud`/REST API
	names.

	If you look at the [`google_compute_instance documentation`](/docs/providers/google/r/compute_instance.html),
	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:

	```hcl
	resource "google_compute_instance" "vm_instance" {
	name = "terraform-instance"
	machine_type = "e2-micro"

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

	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:

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

	This will create [VPC network resource](/docs/providers/google/r/compute_network.html)
	with a subnetwork in each region. Next, change the network of the
	`google_compute_instance` from the `"default"` network to the new network.

	```diff
	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 on your workstation is to use the Google Cloud SDK as we mentioned earlier.

	You can also use a Google Cloud Service Account with terraform.

	From [the service account key page in the Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts)
	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.

	```bash
	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](/docs/providers/google/guides/provider_reference.html) for more information.

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

	### Using Terraform Cloud as the Backend
	You need to use a different [environment variable](https://www.terraform.io/docs/cloud/workspaces/variables.html) name to store your credentials in Terraform Cloud.
	1. Create an environment variable called `GOOGLE_CREDENTIALS` in your Terraform Cloud workspace.
	2. Remove the newline characters from your JSON key file and then paste the credentials into the environment variable value field. (Running `cat CREDENTIALS.json \| tr -s '\n' ' '` will remove newline characters from your JSON key file)
	3. Mark the variable as Sensitive and click Save variable.

	All runs within the workspace will use the `GOOGLE_CREDENTIALS` variable to authenticate with Google Cloud Platform.

	~> Note: When running inside a CLI-driven TFC workspace, local environment variables will only be accessible when executed [locally](https://www.terraform.io/cloud-docs/workspaces/settings#execution-mode). All credentials environment variables (including default application credentials) need to be set in the [Variables tab](https://www.terraform.io/cloud-docs/workspaces/variables/managing-variables#workspace-specific-variables) in order to be accessible by workspaces executed remotely.

	## Provisioning your resources
	By now, your config will look something like:

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

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

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

	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:

	```hcl
	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](/docs/providers/google/guides/provider_reference.html) for more details on configuring
	the provider block (including how you can eliminate it entirely!).

	You can also check out the [GCP Community tutorials](https://cloud.google.com/community/tutorials/)
	such as:

	* [Getting started with Terraform on Google Cloud Platform](https://cloud.google.com/community/tutorials/getting-started-on-gcp-with-terraform)

	* [Managing GCP Projects with Terraform](https://cloud.google.com/community/tutorials/managing-gcp-projects-with-terraform)

	* [Modular Load Balancing with Terraform](https://cloud.google.com/community/tutorials/modular-load-balancing-with-terraform)