Pre-Commit for Terraform: A Step-by-Step Guide

Terraform is a powerful tool for managing your infrastructure as code, but mistakes can happen. Wouldn’t it be great to catch those errors before they even reach your infrastructure? That’s where pre-commit comes in. This handy utility lets you run checks (like formatting, linting, and validation) on your Terraform code before each commit, ensuring quality and consistency.

This guide will walk you through installing and configuring pre-commit specifically for Terraform, focusing on Linux but also touching on macOS and Windows where relevant.

What is Pre-Commit?

pre-commit is a framework for managing and running hooks (scripts) before you commit code. Think of it as a gatekeeper for your commits. It allows you to define a set of checks that must pass before a commit is allowed. If any check fails, the commit is aborted, giving you a chance to fix the issues. This prevents bad code from ever entering your repository, leading to fewer surprises and a smoother development workflow.

Why Use Pre-Commit with Terraform?

Terraform code can be complex, and even small errors can have significant consequences. pre-commit helps you avoid these pitfalls by:

• Enforcing code style: Consistent formatting makes your Terraform code easier to read and maintain.
• Catching syntax errors: Identify typos and structural issues early.
• Validating Terraform configurations: Ensure your Terraform code is valid and adheres to best practices.
• Improving collaboration: Pre-commit hooks provide a standard set of checks that everyone on your team must adhere to, improving collaboration and code consistency.

Installation

Linux

1. Install pre-commit: The recommended way is using your distribution’s package manager. For example,

On Debian/Ubuntu:

sudo apt-get install pre-commit

On Fedora/CentOS/RHEL:

sudo dnf install pre-commit
pre-commit installed at .git/hooks/pre-commit

Alternatively, you can install it using pip:

pip install pre-commit

2. Verify installation:

pre-commit --version
pre-commit 4.1.0

macOS

The easiest way to install pre-commit on macOS is using Homebrew:

brew install pre-commit

Or, again, you can use pip:

pip install pre-commit

Windows

On Windows, you can use Chocolatey:

choco install pre-commit

Or, you guessed it, pip:

pip install pre-commit

Configuration: .pre-commit-config.yaml

The heart of pre-commit is the .pre-commit-config.yaml file, which lives in the root of your Terraform project. This file defines the hooks you want to run. Here’s a basic example for Terraform:

repos:
-   repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.78.0 # Use a specific version for reproducibility
    hooks:
    -   id: terraform_fmt
    -   id: terraform_validate
    -   id: terraform_tflint # Optional: For more advanced linting. Install tflint separately if you use this.

Let’s break this down:

• repos: This section lists the repositories containing the hooks. In this case, we’re using the pre-commit-terraform repository, which provides a collection of useful Terraform hooks.
• rev: Specifies the version of the hook repository. It’s crucial to pin to a specific version to ensure consistent behavior across different machines and over time. Update this periodically to benefit from new features and bug fixes.
• hooks: This section lists the specific hooks you want to use.
  • terraform_fmt: Runs terraform fmt to format your Terraform code according to the standard style.
  • terraform_validate: Runs terraform validate to check the syntax and validity of your Terraform configurations.
  • terraform_tflint: (Optional) Runs tflint for more in-depth linting. You’ll need to install tflint separately if you want to use this hook. See the tflint documentation for installation instructions.

Running Pre-Commit

Once you’ve created the .pre-commit-config.yaml file, you can run pre-commit manually:

pre-commit run

This will run all the configured hooks against your staged files.

Integrating with Git

The real power of pre-commit comes from integrating it with Git. This makes the checks automatic. To do this, run:

pre-commit install

This will install the pre-commit hook in your Git repository. Now, every time you try to commit, pre-commit will run the checks. If any check fails, the commit will be aborted.

Updating Hooks

Periodically, you should update your hooks to benefit from improvements and bug fixes. You can do this by updating the rev in your .pre-commit-config.yaml file and then running:

pre-commit update

Conclusion

pre-commit is an invaluable tool for ensuring the quality and consistency of your Terraform code. By automating checks before each commit, you can catch errors early, improve collaboration, and ultimately deploy infrastructure with greater confidence. So, add it to your Terraform workflow today and experience the benefits of a cleaner, more reliable codebase.