Terraform Starter Boilerplate for GCP using Terragrunt

The Boilerplate Github Repositories (stars are welcome ⭐)

• What you deploy: https://github.com/MeteorOps/terragrunt-gcp-projects
• Modules you can use: https://github.com/MeteorOps/terraform-gcp-modules ‍

Terraform mistakes that made me build this boilerplate

I built this boilerplate for a reason.

I saw what companies regret with how they implemented Terraform:

• Writing all of the Terraform code in one main.tf file
• Copy-pasting resources manually
• Copy-pasting configuration throughout the codebase
• No state separation and environment awareness

This is why they regretted the above:

• One terraform apply could ruin an entire environment
• Resources modifications required changes in multiple locations
• Configuration modifications required changes in multiple locations
• Accidentally deploying the wrong resources to the wrong environment

And so, I built this boilerplate for our clients (and you) to minimize regrets.

The focus of this boilerplate is managing GCP resources.

Is this boilerplate for you?

If you're a CTO, a DevOps lead embarking on a new project on GCP, or simply in search of a template to organize your Terraform repositories, this project is for you. Finding a well-structured example for deploying GCP resources can be challenging. My own search for such a template was unfruitful, leading me to develop a solution that I've decided to share openly and discuss in this article.

What should you expect from this guide?

By the conclusion of this guide, you'll have a thorough understanding of how to establish Terraform repositories using a best-practice folder structure for provisioning GCP resources. You'll also be equipped to execute a straightforward demo, witnessing an end-to-end workflow in action.

What shouldn't you expect from this guide?

An exhaustive library of modules for every resource in GCP. We kept the boilerplate minimal, so that you can utilize it for your needs.
You can fairly easily utilize existing modules you created or found using the boilerplate.

Getting Started

To begin, clone the essential repositories:‍

Primary Repository
Clone the terragrunt-gcp-projects repository to get started.

git clone git@github.com:MeteorOps/terragrunt-gcp-projects.git

Modules Repository (Optional)

For the modules used, clone the terraform-gcp-modules repository.

git clone git@github.com:MeteorOps/terraform-gcp-modules.git

Repository Structure Explained

The code organization follows a logical hierarchy to facilitate multiple projects, regions or environments.This structure gives you a number of benefits:

• Hierarchical configuration: The configuration at each level cascades through the folders under it
• State separation: The terraform state is saved per folder in a different path in a bucket, limiting the impact radius of changes
• Dynamic-level of deployment: The deeper into the folder you go, the more specific resources you affect with one deployment

project
└ _global
└ region
   └ _global
   └ environment
      └ resource

Creating and using root (project) level variables

When dealing with multiple GCP projects or regions, passing common variables to modules can become repetitive. To avoid duplicating variables across each terragrunt.hcl file, leverage root terragrunt.hcl inputs to inherit variables seamlessly across regions and environments.

Deploy Using Terragrunt

Prerequisites

Install Terraform version 0.12.6 or newer and Terragrunt version v0.25.1 or newer.
Fill in your GCP Project ID in my-project/project.hcl.
Make sure the gcloud CLI is installed and you are authenticated, otherwise run gcloud auth login.

Module Deployment

To deploy a single module:

1. cd into the module's folder (e.g. cd my-project/us-central1/rnd-1/vpc).
2. Run terragrunt plan to see the changes you are about to apply.
3. If the plan looks good, run terragrunt apply.

Environment Deployment

To deploy all modules within an environment:

1. cd into the environment folder (e.g. cd my-project/us-central1/rnd-1).
2. Run terragrunt run-all plan to see all the changes you are about to apply.
3. If the plan looks good, run terragrunt run-all apply.

Testing Deployed Infrastructure

Post-deployment, modules will output relevant information. For instance the IP of a deployed application:

Outputs:

ip = "35.240.219.84"

A minute or two after the deployment finishes, you should be able to test the ip output in your browser or with curl:

curl 35.240.219.84

# Output: Let MeteorOps know if this boilerplate needs any improvement!

Clean-Up Process

To remove all deployed modules within an environment:

1. cd into the environment folder (e.g. cd my-project/us-central1/rnd-1).
2. Run terragrunt run-all plan -destroy to see all the destroy changes you're about to apply.
3. If the plan looks good, run terragrunt run-all destroy. ‍

Conclusion

This guide walks you through leveraging best practices for setting up and managing Terraform repositories for GCP with Terragrunt. These methodologies are designed to be straightforward, efficient, and easily adaptable to future projects or company needs.

P.S.

Feel free to subscribe to our Newsletter and learn about other insights and resources we release 👈🏼