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.

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:

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.

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:

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:

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

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:

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:

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.

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:

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

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

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

Cleanup

Clean up downloaded archives.

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.