Deploy your foundation using Terraform downloaded from the console

The Cloud foundation setup guide in the Google Cloud console allows enterprise administrators to configure an enterprise-ready Google Cloud foundation using a guided interface and deploy it directly from the Google Cloud console or download it as Terraform.

Administrators can configure an organization entity, users & groups; link or set up a billing account; and configure resource (folders & projects) hierarchy, IAM policies, initial networking, and centralized logging and monitoring.

When customers download their configuration as Terraform, the console generates a Terraform file for later deployment. This tutorial provides instructions for deploying the downloaded Terraform file and takes into consideration any previously deployed infrastructure resources.

Before you begin

Review Best practices for using 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, 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.

Deploy Terraform with Cloud Shell

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.
  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. 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://tf-state-PROJECT_ID
    
  7. Define a Terraform backend configuration within a backend.tf file and replace PROJECT_ID to match the project ID that you used in the previous step. For more details, review storing Terraform state in Cloud Storage.

    # backend.tf
    terraform {
          backend "gcs" {
            bucket  = "tf-state-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.
    

  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 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.
  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://tf-state-PROJECT_ID/terraform/state/
    
    Example output:
    gs://tf-state-PROJECT_ID/terraform/state/default.tfstate
    

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

    # backend.tf
    terraform {
          backend "gcs" {
            bucket  = "tf-state-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.
    

  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 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, 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:

    1. Lock the deployment.
    2. Download the state file.
    3. 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.

  3. To redeploy the Terraform configuration, see Redeploy Terraform with Cloud Shell.

Troubleshooting Terraform deployments

Deploy Terraform with existing resources

If the downloaded Terraform configuration attempts to create resources that already exist, Terraform exits with a 409 error code. 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 into your Terraform state.

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

We recommend following this tutorial 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.