This document provides version control best practices to consider when usingTerraform for Google Cloud.

As with other forms of code, store infrastructure code in version control topreserve history and allow easy rollbacks.

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

Use a default branching strategy

For all repositories that contain Terraform code, use the following strategy bydefault:

• Themain branch is the primary development branch and represents thelatest approved code. Themain branch isprotected.
• Development happens on feature and bug-fix branches that branch off of themain branch.
  • Name feature branchesfeature/$feature_name.
  • Name bug-fix branchesfix/$bugfix_name.
• When a feature or bug fix is complete, merge it back into themain branchwith a pull request.
• To prevent merge conflicts, rebase branches before merging them.

Use environment branches for root configurations

For repositories that include root configurations that are directly deployed toGoogle Cloud, a safe rollout strategy is required. We recommendhaving a separatebranch for each environment. Thus, changes to the Terraformconfiguration can be promoted bymerging changes between the different branches.

Allow broad visibility

Make Terraform source code and repositories broadly visible and accessibleacross engineering organizations, to infrastructure owners (for example, SREs)and infrastructure stakeholders (for example, developers). This ensures thatinfrastructure stakeholders can have a better understanding of theinfrastructure that they depend on.

Encourage infrastructure stakeholders to submit merge requests as part of thechange request process.

Never commit secrets

Never commit secrets to source control, including in Terraform configuration.Instead, upload them to a system likeSecret Manager and reference them by using datasources.

Keep in mind that such sensitive values might still end up in the state fileand might also be exposed as outputs.

Organize repositories based on team boundaries

Although you can use separate directories to manage logical boundaries betweenresources, organizational boundaries and logistics determinerepositorystructure. In general, use the design principle that configurations withdifferent approval and management requirements are separated into differentsource control repositories. To illustrate this principle, these are somepossible repository configurations:

• One central repository: In this model, all Terraform code iscentrally managed by a single platform team. This model works best whenthere is a dedicated infrastructure team responsible for all cloudmanagement and approves any changes requested by other teams.

• Team repositories: In this model, each team is responsible for theirown Terraform repository where they manage everything related to theinfrastructure they own. For example, the security team might have arepository where all security controls are managed, and application teamseach have their own Terraform repository to deploy and manage theirapplication.

  Organizing repositories along team boundaries is the best structure for mostenterprise scenarios.

• Decoupled repositories: In this model, eachlogical Terraformcomponent is split into its own repository. For example, networking mighthave a dedicated repository, and there might be a separate project factoryrepository for project creation and management. This works best in highlydecentralized environments where responsibilities frequently shift betweenteams.

Sample repository structure

You can combine these principles to split Terraform configuration acrossdifferent repository types:

• Foundational
• Application and team-specific

Foundational repository

Afoundational repository that contains major centralcomponents, such as folders or org IAM. This repositorycan be managed by the central cloud team.

• In this repository, include a directory for each majorcomponent (for example, folders, networks, and so on).
• In the component directories, include a separate folder for eachenvironment (reflecting the directory structure guidance mentioned earlier).

Application and team-specific repositories

Deployapplication and team-specific repositories separately for eachteam to manage their unique application-specific Terraform configuration.

What's next

• Learn aboutbest practices for Terraform operations.
• Learn aboutbest practices for using Terraform securely.