This document provides guidelines and recommendations for Terraform operations.

This guide is not an introduction to Terraform. For an introduction to usingTerraform with Google Cloud, seeGet started with Terraform.

Always plan first

Always generate a plan first for Terraform executions.Save the plan to an output file.After an infrastructure owner approves it, execute the plan. Even whendevelopers are locally prototyping changes, they should generate a plan andreview the resources to be added, modified, and destroyed before applying theplan.

Implement an automated pipeline

To ensure consistent execution context, execute Terraform through automatedtooling. If a build system (like Jenkins) is already in use and widely adopted,use it to run theterraform plan andterraform apply commands automatically.If no existing system is available, adopt eitherCloud BuildorTerraform Cloud.

Use service account credentials for continuous integration

When Terraform is executed from a machine in a CI/CD pipeline, it shouldinherit the service account credentials from the service executing the pipeline.Wherever possible, run CI pipelines on Google Cloud becauseCloud Build, Google Kubernetes Engine, or Compute Engine inject credentialswithout downloading service account keys.

For pipelines that run outside of Google Cloud, preferworkload identity federationto obtain credentials without downloading service account keys.

Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keyswhenever possible. If you must authenticate with a service account key, you are responsible for thesecurity of the private key and for other operations described by Best practices for managing service account keys.If you are prevented from creating a service account key, service account key creation mightbe disabled for your organization. For more information, see Managing secure-by-default organization resources.

If you acquired the service account key from an external source, you must validate it before use.For more information, see Security requirements for externally sourced credentials.

Avoid importing existing resources

Where possible, avoid importing existing resources(usingterraform import), because doingso can make it challenging to fully understand the provenance and configurationof manually created resources. Instead, create new resources through Terraformand delete the old resources.

In cases where deleting old resources would create significant toil,use theterraform import command with explicit approval. After a resource isimported into Terraform, manage it exclusively with Terraform.

Google provides a tool that you can use to import yourGoogle Cloud resources into Terraform state. For more information,seeImport your Google Cloud resources into Terraformstate.

Don't modify Terraform state manually

The Terraform state file is critical for maintaining the mapping betweenTerraform configuration and Google Cloud resources. Corruption can leadto major infrastructure problems. When modifications to the Terraform state arenecessary, use theterraform state command.

Regularly review version pins

Pinning versions ensures stability but prevents bug fixes and otherimprovements from being incorporated into your configuration. Therefore,regularly review version pins for Terraform, Terraform providers, and modules.

To automate this process, use a tool such asDependabot.

Use application default credentials when running locally

When developers are locally iterating on Terraform configuration, they shouldauthenticate by runninggcloud auth application-default loginto generate application default credentials. Don't download service accountkeys, because downloaded keys are harder to manage and secure.

Set aliases to Terraform

To make local development easier, you can add aliases to your command shellprofile:

• alias tf="terraform"
• alias terrafrom="terraform"

What's next

• Learn aboutbest practices to securely use Terraform.
• Learn aboutbest practices for testing Terraform modules and configurations.