Terraform Starter Boilerplate for GCP using Terragrunt
Tags: terraform, devops, googlecloud, terragrunt
Published: 2024-04-26 11:16:24

## 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](https://meteorops.beehiiv.com/subscribe) and learn about other insights and resources we release 👈🏼