Terraform Cookbook: Development Environment Recipe

TLDR: This tutorial provides a step-by-step guide to setting up a complete Terraform development environment, including version management (tenv), documentation generation (terraform-docs), linting (TFLint), security scanning (Trivy, Checkov), pre-commit hooks, and others. We use a cookbook-style approach for easy understanding, but if you just want the command script to set up the environment, you can get it here.

Terraform Cookbook: Development Environment Recipe

A quick and easy recipe to set up a killer development environment for writing Terraform modules. Tested on Linux Ubuntu 24.04.1 LTS for x86_64 architecture (should work on other debian-based systems. For other Linux distributions, some tweaks are required).

Building robust and secure infrastructure with Terraform requires more than just the terraform CLI. A well-equipped development environment is crucial for maximizing productivity, ensuring code quality, and preventing costly mistakes. This tutorial serves as your complete recipe for setting up a top-notch Terraform development environment. I'll guide you through installing and configuring essential tools. By the end of this tutorial, you will have a streamlined workflow, enabling you to focus on building infrastructure rather than managing complex configurations. We use a cookbook-style approach for easy understanding.

Ingredients:

Linux utilities (curl, jq, tar, unzip, git)
tenv: version manager for Terraform
terraform CLI: HashiCorp's Terraform CLI
terraform-docs: tool for generating module documentation
TFLint: terraform linter
Trivy: security scanner for IaC and dependencies
venv: virtual environments for Python
Pre-commit: git hook manager
Pre-commit-terraform: terraform git hooks
Checkov: static analysis for IaC
VSCode: code editor with Terraform extension

Preparation Steps:

1. Know Your Kitchen, VSCode.

First things first, every chef needs a well-equipped kitchen. In our case, Visual Studio Code is our kitchen, the place where we'll craft all our infrastructure recipes. But a bare kitchen isn't enough. We need the right tools and appliances to prepare delicious dishes. That's where the Terraform extension by Hashicorp comes in. The extension provides syntax highlighting, code completion, among other features.

1
2
3
4
5
6
7
8
9
10
# Follow the VSCode installation guide (https://code.visualstudio.com/docs/setup/linux) for other instalation methods.
sudo apt-get install curl

curl -L -o vscode.deb  https://go.microsoft.com/fwlink/?LinkID=760868

sudo apt install ./vscode.deb

code 
# After VSCode launch, use Quick Open (Ctrl+P), paste the command "ext install HashiCorp.terraform" and press enter.
# Or install the extension @id:HashiCorp.terraform using the VSCode GUI.

2. Equip Your Kitchen with `tenv`.

Manage multiple Terraform versions like a pro. Simplifies the management of multiple Terraform versions, ensuring compatibility with different projects.

Grab your Terraform version manager, tenv. Every good chef needs a well-organized kitchen. When it comes to managing different versions of Terraform, tenv will keep your environment neatly organized and easily accessible. It also supports OpenTofu, Terragrunt, and Atmos. Let's get it installed:

1
2
3
4
5
6
7
8
9
10
11
12
13
TENV_LATEST=$(curl -s https://api.github.com/repos/tofuutils/tenv/releases/latest | jq -r '.assets[] | select(.name | endswith("Linux_x86_64.tar.gz")) | .browser_download_url')

curl -L -O $TENV_LATEST

mkdir ~/.tenv

tar xvzf $(echo $TENV_LATEST | grep -o -E "tenv_v.*") -C ~/.tenv

export PATH="$HOME/.tenv:$PATH"

tenv completion bash > ~/.tenv/tenv_completion.bash

echo -e '\n# tenv and terraform tools\nexport PATH="$HOME/.tenv:$PATH"\nsource $HOME/.tenv/tenv_completion.bash' >> ~/.bashrc

The lines added to .bashrc ensure that tenv is always available when we start cooking terraform modules.

3. Grab Your Trusty `terraform` CLI Using `tenv`.

It's time to grab our most essential infrastructure cooking utensil, our pan: the terraform CLI. This is the workhorse of our infrastructure kitchen – the pan we'll use to cook up all our infrastructure recipes. We'll use tenv to fetch and install the perfect pan for the job. If you wish, use Opentofu, which is an "more open" source altenative.

1
2
3
tenv terraform install

terraform -install-autocomplete

This is like reaching into our neatly organized tools rack and selecting the perfect terraform CLI pan.

4. Compile Your Infrastructure Recipe Notebook With `terraform-docs`.

Automatically generate documentation for your terraform modules (inputs, outputs, etc.).

A good chef keeps a detailed recipe notebook, documenting each dish's ingredients, instructions, and variations. In the world of infrastructure as code, terraform-docs is our tool to maintain recipe documents. It automatically generates documentation for our Terraform modules, neatly organizing inputs, outputs, and other important details. This ensures that anyone (including our future selves) can easily understand and use our infrastructure recipes. Let's add it to our kitchen:

1
2
3
4
5
6
7
8
9
TDOC_LATEST=$(curl -s https://api.github.com/repos/terraform-docs/terraform-docs/releases/latest | jq -r '.assets[] | select(.name | endswith("linux-amd64.tar.gz")) | .browser_download_url')

curl -L -O $TDOC_LATEST

tar xzf $(echo $TDOC_LATEST | grep -o -E "terraform-docs-.+") -C ~/.tenv terraform-docs

terraform-docs completion bash > ~/.tenv/terraform-docs_completion.bash

echo -e '\nsource $HOME/.tenv/terraform-docs_completion.bash' >> ~/.bashrc

5. Employ TFLint Quality Control.

A linter for Terraform code. Catch syntax errors, enforce standards, and keep your Terraform configs clean.

Maintaining quality control is crucial. In the Terraform kitchen, TFLint scans our Terraform code for syntax errors and potential issues, ensuring our code is sound. Let's add this to our kitchen:

1
2
3
4
5
TFLINT_LATEST=$(curl -s https://api.github.com/repos/terraform-linters/tflint/releases/latest | jq -r '.assets[] | select(.name | endswith("tflint_linux_amd64.zip")) | .browser_download_url')

curl -L -O $TFLINT_LATEST

unzip -o $(echo $TFLINT_LATEST | grep -o -E "tflint_linux.+") -d ~/.tenv

The .tflint.hcl file is the configuration file for TFLint. Its purpose is to define the rules, plugins, and configurations that TFLint will use when analyzing your Terraform code. This allows you to enforce best practices, identify issues, and customize the linter's behavior to align with your project requirements. The configuration I currently use for terraform AWS resources is like the bellow example.

Sample `.tflint.hcl` Configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
tflint {
  required_version = "~> 0.54.0"
}

plugin "terraform" {
  enabled = true
  preset  = "all"
}

plugin "aws" {
  enabled = true
  version = "0.36.0"
  source  = "github.com/terraform-linters/tflint-ruleset-aws"
  deep_check = true
}

rule "aws_resource_missing_tags" {
  enabled = true
  tags = [
    "env"
  ]
}

6. Double Strain Your Infrastructure Code With `Trivy` And `Checkov`.

Trivy scan your IaC files, container images, and dependencies for vulnerabilities.

Checkov detects misconfigurations, security risks, and compliance violations in Terraform and other IaC templates.

Ensuring the safety of your code is paramount. You wouldn't want any unwanted bits sneaking into your dishes. Just as a chef uses strainers to remove impurities, we use Trivy and Checkov to filter out potential vulnerabilities and misconfigurations from our infrastructure code. Think of them as two different types of strainers, each catching different kinds of unwanted elements. Let's add them:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
TRIVY_LATEST=$(curl -s https://api.github.com/repos/aquasecurity/trivy/releases/latest | jq -r '.assets[] | select(.name | endswith("Linux-64bit.tar.gz")) | .browser_download_url')

curl -L -O $TRIVY_LATEST

tar xzf $(echo $TRIVY_LATEST | grep -o -E "trivy_.+") -C ~/.tenv trivy

# We are going to install checkov using python pip and venv
sudo apt install python3-pip python3.12-venv

python3 -m venv ~/.venv

source ~/.venv/bin/activate

pip install checkov

Now, with both Trivy and Checkov in our kitchen, we can confidently cook a safe and secure code. This double-straining approach provides a more comprehensive security check, catching both specific vulnerabilities and broader misconfigurations.

7. Set Up Your `pre-commit` Kitchen Workflow Checklist

Ensures consistent code quality by running checks (e.g., linting, formatting, security scans) before committing code.

In a busy kitchen, chefs rely on checklists and workflows to ensure every step is followed and no crucial task is missed. pre-commit acts as our kitchen workflow checklist, ensuring we systematically employ all our quality control and tools (like TFLint, Trivy, and Checkov) before we "serve" (commit) our infrastructure code.

pre-commit uses git hooks, which are scripts that run automatically at specific points in the Git workflow. In this case, we're going to use pre-commit hooks, which run before each git commit. This ensures that our code is always checked before it's added to the project's history. Let's set up our kitchen workflow checklist:

1
2
3
source ~/.venv/bin/activate

pip install pre-commit

Now that we have pre-commit installed, we'll configure it to use our quality control tools. The .pre-commit-config.yaml file is the configuration file for the Pre-commit framework that define the pre-commit hook.

Sample `.pre-commit-config.yaml` Configuration.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.96.2
    hooks:
      - id: terraform_validate
      - id: terraform_fmt
      - id: terraform_tflint
        args:
          - --args=--config=__GIT_WORKING_DIR__/.tflint.hcl
      - id: terraform_trivy
      - id: terraform_checkov
        name: "Terraform validate with Checkov"
        args:
          - --args=--quiet
      - id: terraform_docs

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: detect-aws-credentials
        name: "Pre-commit detect AWS credentials"
      - id: detect-private-key
        name: "Pre-commit detect private keys"
      - id: end-of-file-fixer
        name: "Pre-commit fix end of files"
      - id: trailing-whitespace
        name: "Pre-commit remove trailing whitespaces"

Beyond quality and safety, presentation matters too! Just as chefs ensure consistent dish presentation, we also use terraform fmt and others pre-commit hooks to format our code in a consistent way. This makes our code easier to read, understand, and maintain, both for ourselves and our colleagues.

Now that our kitchen is equipped, it's time to gather the ingredients for our infrastructure main dish: the Terraform root module.

8. Our Main Infrastructure Dish: The Terraform Root Module.

Just like any good recipe, it requires the right ingredients, organized in the right way. HashiCorp suggests a standard module structure, which we'll follow to ensure a well-structured and maintainable code. Here is an example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
root-module/
├── README.md
├── main.tf
├── variables.tf
├── outputs.tf
├── providers.tf
├── modules/
│   ├── child-module-A/
│   │   ├── README.md
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── outputs.tf
│   ├── child-module-B/
│   ├── .../
├── .pre-commit-config.yaml
└── .tflint.hcl

With our main dish structure defined, let's dive into a sample recipe specifically for AWS dishes.

A Sample Recipe for AWS

A template that serves as a foundation for creating Terraform modules.

Here is a handy module template to bootstrap your AWS resources. It serves as a foundation starting point for various AWS infrastructure creations, and includes essential ingredients for a robust and secure AWS setup, including:

An S3 Bucket for State Storage. It includes server-side encryption, versioning, and lifecycle rules for noncurrent object transition and expiration, ensuring the safety and management of our stored data. It also blocks public access, preventing unwanted access.
A DynamoDB Table for State Locking. This acts as a coordination system in our kitchen, preventing conflicts when we have multiple chefs.

Template usage example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
aws configure # You will need the AWS CLI installed. Set up AWS credentials with privileges to provision resources. Remember to use temporary credentials or store permanent credentials outside the git repository.

git clone https://github.com/zidenis/terraform-module-template-aws.git my-terraform-module

cd my-terraform-module

git remote remove origin # We remove the original remote to start our own module

# Do not run this script if your intention is to develop the module locally.
chmod +x backend_bootstrap.sh; ./backend_bootstrap.sh # optionally, use this bash script to set up the remote backend. 

source ~/.venv/bin/activate

pre-commit install --install-hooks # set up your git repository to run pre-commit hooks automatically

pre-commit run -a # optionally, run pre-commit hooks against all the files.

You can now start developing your specific module, using the provided structure and backend setup as a solid foundation. Using pre-commit, you can run all the quality and security checks we set up earlier, ensuring a perfect and secure final dish.

pre-commit usage example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
source ~/.venv/bin/activate

echo "# cooking a new module" >>  main.tf

git add main.tf

git commit -m "Cooking a new module"
# [INFO] Initializing environment for https://github.com/antonbabenko/pre-commit-terraform.
# [INFO] Initializing environment for https://github.com/pre-commit/pre-commit-hooks.
# [INFO] Installing environment for https://github.com/pre-commit/pre-commit-hooks.
# [INFO] Once installed this environment will be reused.
# [INFO] This may take a few minutes...
# Terraform validate.......................................................Passed
# Terraform fmt............................................................Passed
# Terraform validate with tflint...........................................Passed
# Terraform validate with trivy............................................Passed
# Terraform validate with Checkov..........................................Passed
# Terraform docs...........................................................Passed
# Pre-commit detect AWS credentials........................................Passed
# Pre-commit detect private keys...........................................Passed
# Pre-commit fix end of files..............................................Passed
# Pre-commit remove trailing whitespaces...................................Passed

Conclusion

By following this recipe, you've equipped your development environment with essential tools to write, validate, and secure Terraform modules effectively. This tutorial was designed to install the latest versions of the tools, but remember to regularly update your tools and configurations for optimal performance and compliance.

Are there any additional tools or configurations you'd like to explore to complement the setup? are you using Generative AI to develop your terraform modules? please, tell me how. While Generative AI has the potential to streamline Terraform development by automating certain tasks like code generation or identifying potential issues. However, at this stage, I think it's likely not a core component for most users setting up a development environment. This is something that I plan to investigate.

Let me know your thoughts and suggestions to improve this guide further. Happy coding!

Tools versions at the time of writing

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
tenv version
# tenv version v3.2.11

terraform version
# Terraform v1.10.3
# on linux_amd64

terraform-docs version
# terraform-docs version v0.19.0 af31cc6 linux/amd64

tflint --version
# TFLint version 0.54.0
# + ruleset.terraform (0.10.0-bundled)

trivy --version
# Version: 0.58.0

checkov --version
# 3.2.343

pre-commit --version
#pre-commit 4.0.1

Cleanup

Clean up downloaded archives.

1
2
3
4
5
6
7
8
9
rm $(echo $TENV_LATEST | grep -o -E "tenv_v.*")

rm $(echo $TDOC_LATEST | grep -o -E "terraform-docs-.+")

rm $(echo $TFLINT_LATEST | grep -o -E "tflint_linux.+")

rm $(echo $TRIVY_LATEST | grep -o -E "trivy_.+")

rm vscode.deb

This text was originally published in: https://gist.github.com/zidenis/93f8f93429e443c72243889b18bccad1

Select your cookie preferences

Site Terms, Privacy, and more.

Terraform Cookbook: Development Environment Recipe

A step-by-step guide for a complete Terraform development env, including version management, documentation generation, linting, security scanning, and more.