<br />

[Google Cloud Setup](https://console.cloud.google.com/cloud-setup) helps administrators configure a
Google Cloud foundation using a [guided flow](https://docs.cloud.google.com/docs/enterprise/cloud-setup), and
deploy directly from the Google Cloud console or download as Terraform.

> [!WARNING]
> **Warning:** If you plan to deploy a downloaded Terraform configuration using [your
> own pipeline](https://docs.cloud.google.com/docs/enterprise/deploy-foundation-using-terraform-from-console#manage), don't click the Deploy button in the console. If you already clicked the Deploy button, see [Deploy downloaded Terraform after deploying from
> the console](https://docs.cloud.google.com/docs/enterprise/deploy-foundation-using-terraform-from-console#deploy-terraform-after-console).

This document helps you deploy your Google Cloud Setup Terraform file.

## Before you begin

Review [Best practices for using Terraform](https://docs.cloud.google.com/docs/terraform/best-practices-for-terraform), which includes guidelines for effective development with Terraform across team members and workstreams.

If you already deployed the foundation configuration by clicking the Deploy button in the console, and now want to deploy a downloaded Terraform configuration using [your own pipeline](https://docs.cloud.google.com/docs/enterprise/deploy-foundation-using-terraform-from-console#manage), you must do the following:

- Download the Terraform state file that was generated by the console.
- Include the downloaded state file in your own pipeline process.

For more information, see [Deploy downloaded Terraform after deploying from the console](https://docs.cloud.google.com/docs/enterprise/deploy-foundation-using-terraform-from-console#deploy-terraform-after-console).

## Deploy Terraform with Cloud Shell

> [!NOTE]
> **Note** : If you have previously deployed the downloaded Terraform configuration, proceed to the [redeploy section](https://docs.cloud.google.com/docs/enterprise/deploy-foundation-using-terraform-from-console#redeploy).

Cloud Shell comes with Terraform pre-installed and pre-authenticated, so you can get
started quickly.

1. From the in-console setup guide, click **Download as Terraform** and save the configuration.
2. Open [Cloud Shell](https://shell.cloud.google.com).
3. In Cloud Shell, create a directory and navigate to it:

   ```
   mkdir cloud-foundation-example && cd cloud-foundation-example
   ```
4. Upload the Terraform configuration that you downloaded in step 1.

   From the Cloud Shell **More** menu,
   select **Upload** , and then click **Choose Files** to select the Terraform configuration.
   Set the destination directory to the folder that you created in the previous step, and then
   click **Upload**.
5. Ensure that you're in the `cloud-foundation-example` directory.

6. Create a Cloud Storage bucket to store [Terraform Remote State](https://docs.cloud.google.com/docs/terraform/resource-management/store-state).
   A remote state lets Terraform use object stores like Cloud Storage to store state
   information about your Terraform-managed infrastructure. This configuration provides
   benefits such as team delegation and state locking.

   To create the Cloud Storage bucket, run the following command:

   ```
   gcloud storage buckets create gs://tfstate-PROJECT_ID
   ```
7. Define a Terraform backend configuration within a `backend.tf` file and replace
   <var translate="no">PROJECT_ID</var> to match the project ID that you used in the previous step. For more details,
   review [storing Terraform state in Cloud Storage](https://docs.cloud.google.com/docs/terraform/resource-management/store-state#create_the_bucket).

   ```
   # backend.tf
   terraform {
         backend "gcs" {
           bucket  = "tfstate-PROJECT_ID"
           prefix  = "terraform/state"
         }
   }
   ```
8. Run `terraform init`. This process initializes your working directory that contains
   the Terraform configuration files and the backend.

9. Run `terraform plan` to see the resources Terraform creates. Example output:

   ```
   ...
   Plan: 6 to add, 0 to change, 0 to destroy.
   Note: You didn't use the -out option to save this plan, so Terraform can't
   guarantee to take exactly these actions if you run "terraform apply" now.
   ```

   <br />

10. Apply the configuration by running `terraform apply`, which deploys your resources to
    Google Cloud. When prompted, enter `yes`.

11. [Explore the Google Cloud console](https://console.cloud.google.com/cloud-resource-manager) to verify that
    your resources are now deployed on your account or project.

## Redeploy Terraform with Cloud Shell

Terraform stores information about deployed resources within the
Terraform state file. If you have followed the previous steps to deploy
your configuration, we strongly recommend that you reuse the same backend
to automatically detect, prune, and update resources defined by the new exported
configuration.

1. From the in-console setup guide, click **Download as Terraform** and save the configuration.
2. Open [Cloud Shell](https://shell.cloud.google.com).
3. In Cloud Shell, create a new directory and navigate to it:

   ```
   mkdir cloud-foundation-example-redeploy && cd cloud-foundation-example-redeploy
   ```
4. Upload the Terraform configuration that you downloaded in step 1.

   From the Cloud Shell **More** menu, select
   **Upload** , and then click **Choose Files** to select the Terraform configuration.
   Set the destination directory to the folder that you created in the previous step, and then click **Upload**.
5. Ensure that you're in the `cloud-foundation-example-redeploy` directory.

6. Ensure that the previously created Cloud Storage backend bucket and state file exists.

   ```
   gcloud storage ls gs://tfstate-PROJECT_ID/terraform/state/
   ```
   Example output:

   ```
   gs://tfstate-PROJECT_ID/terraform/state/default.tfstate
   ```

   <br />

7. Define a Terraform backend configuration within a `backend.tf` file by reusing
   the same bucket and prefix.

   ```
   # backend.tf
   terraform {
         backend "gcs" {
           bucket  = "tfstate-PROJECT_ID"
           prefix  = "terraform/state"
         }
   }
   ```
8. Run `terraform init`. This process initializes your working directory that contains
   the Terraform configuration files and the backend.

9. Run `terraform plan` to see the resources Terraform creates, changes, or destroys.
   Example output:

   ```
   ...
   Plan: 2 to add, 3 to change, 4 to destroy.
   Note: You didn't use the -out option to save this plan, so Terraform can't
   guarantee to take exactly these actions if you run "terraform apply" now.
   ```

   <br />

10. Apply the configuration by running `terraform apply`, which deploys your resources to
    Google Cloud. When prompted, enter `yes`.

11. [Explore the Google Cloud console](https://console.cloud.google.com/cloud-resource-manager) to verify
    that your resources are now deployed on your account or project.

## Deploy downloaded Terraform after deploying from the console

If you already deployed the foundation configuration using the Deploy button in the console, a Terraform state file was generated. If you now want to download the Terraform configuration to deploy using [your own pipeline](https://docs.cloud.google.com/docs/enterprise/deploy-foundation-using-terraform-from-console#manage), you must include the Terraform state file that was generated during your console deployment.

To download and use the state file:

1. To download the Terraform state file, complete the following procedures in [Manage the Terraform state file](https://docs.cloud.google.com/infrastructure-manager/docs/state-file):

   1. [Lock the deployment](https://docs.cloud.google.com/infrastructure-manager/docs/state-file#lock_the_deployment).
   2. [Download the state file](https://docs.cloud.google.com/infrastructure-manager/docs/state-file#download_the_state_file).
   3. [Unlock the deployment](https://docs.cloud.google.com/infrastructure-manager/docs/state-file#unlock_the_deployment).
2. To move the state file you downloaded to a Cloud Storage bucket, see [Store Terraform state in a Cloud Storage bucket](https://cloud.google.com/docs/terraform/resource-management/store-state).

3. To redeploy the Terraform configuration, see [Redeploy Terraform with Cloud Shell](https://docs.cloud.google.com/docs/enterprise/deploy-foundation-using-terraform-from-console#redeploy).

## Troubleshooting Terraform deployments

This section describes how to resolve issues that you might encounter when
deploying Terraform.

### Deploy Terraform with existing resources

If the downloaded Terraform configuration attempts to create resources that
already exist, Terraform exits with a
[`409` error code](https://docs.cloud.google.com/resource-manager/docs/core_errors#CONFLICT).
To resolve these errors, you can delete the resource by using the
Google Cloud console
or gcloud CLI, and then re-apply the Terraform configuration.
Alternatively, if these resources are critical and cannot be deleted, you can
[import resources](https://docs.cloud.google.com/docs/terraform/resource-management/import#manually_importing_resources)
into your Terraform state.

## Manage infrastructure as code with Terraform, Cloud Build, and GitOps

We recommend following this [tutorial](https://docs.cloud.google.com/architecture/managing-infrastructure-as-code) for complete instructions. This option is for platform admins and operators who are looking for a strategy to predictably and repeatedly make changes to infrastructure. The guide assumes that you are familiar with Google Cloud, Linux, and GitHub. The high-level steps of this option are as follows:

1. Set up your GitHub repository.
2. Configure Terraform to store state in a Cloud Storage bucket.
3. Grant permissions to your Cloud Build service account.
4. Connect Cloud Build to your GitHub repository.
5. Change your environment configuration in a feature branch.
6. Promote changes to the development environment.
7. Promote changes to the production environment.