nixpkgs-terraform

This flake exposes a collection of Terraform versions as Nix packages, starting with version 1.0.0. The packages provided can be used for creating reproducible development environments using a nix-shell or devenv.

Important

Starting with version 4.0.0, this project enables allowUnfree by default in order to build Terraform versions with a BSL license.

How it works

This flake provides a set of Terraform versions in the form of:

nixpkgs-terraform.packages.${system}.${version}

Where version is a specific X.Y.Z version or an alias X.Y pointing to the latest patch version within the same cycle, for example, 1.5 points to 1.5.7. The versions.json file contains a complete list of all the available versions and aliases.

Terraform versions are kept up to date via a weekly scheduled CI workflow.

Install

The quickest way to get started with an empty project is to scaffold a new project using the default template:

nix flake init -t github:stackbuilders/nixpkgs-terraform

Alternatively, add the following input to an existing flake.nix file:

inputs.nixpkgs-terraform.url = "github:stackbuilders/nixpkgs-terraform";

Some extra inputs are required for the example provided in the Usage section:

inputs.flake-utils.url = "github:numtide/flake-utils";
inputs.nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";

Binary Cache

It is highly recommended to set up the nixpkgs-terraform binary cache to download pre-compiled Terraform binaries rather than compiling them locally for a better user experience. Add the following configuration to the flake.nix file:

nixConfig = {
  extra-substituters = "https://nixpkgs-terraform.cachix.org";
  extra-trusted-public-keys = "nixpkgs-terraform.cachix.org-1:8Sit092rIdAVENA3ZVeH9hzSiqI/jng6JiCrQ1Dmusw=";
};

Note

Only the most recent versions for each release cycle are pushed to the binary cache; if you are having trouble hitting the cache, try upgrading to the most recent patch version specified in the versions.json file for the corresponding cycle.

Currently, the binary cache supports the following systems:

• aarch64-darwin
• x86_64-darwin
• x86_64-linux

Usage

After configuring the inputs from the Install section, a common use case for this flake could be spawning a nix-shell with a specific Terraform version, which could be accomplished by extracting the desired version from nixpkgs-terraform.packages or by using an overlay as follows:

As a package

outputs = { self, flake-utils, nixpkgs-terraform, nixpkgs }:
  flake-utils.lib.eachDefaultSystem (system:
    let
      pkgs = nixpkgs.legacyPackages.${system};
      terraform = nixpkgs-terraform.packages.${system}."X.Y.Z";
    in
    {
      devShells.default = pkgs.mkShell {
        buildInputs = [ terraform ];
      };
    });

where X.Y.Z is one of the supported versions in the versions.json file.

As an overlay

outputs = { self, flake-utils, nixpkgs-terraform, nixpkgs }:
  flake-utils.lib.eachDefaultSystem (system:
    let
      pkgs = import nixpkgs {
        inherit system;
        overlays = [ nixpkgs-terraform.overlays.default ];
      };
    in
    {
      devShells.default = pkgs.mkShell {
        buildInputs = [ pkgs.terraform-versions."X.Y.Z" ];
      };
    });

where X.Y.Z is one of the supported versions in the versions.json file.

Start a new nix-shell with Terraform in scope by running the following command:

env NIXPKGS_ALLOW_UNFREE=1 nix develop --impure

Note: Due to Hashicorp’s most recent license change the NIXPKGS_ALLOW_UNFREE flag is required for Terraform versions >= 1.6.0, nix develop should work out of the box for older versions.

Templates

This flake provides the following templates:

• default - Simple nix-shell with Terraform installed via nixpkgs-terraform.
• devenv - Using nixpkgs-terraform with devenv.
• terranix - Using nixpkgs-terraform with terranix.

Run the following command to scaffold a new project using a template:

nix flake init -t github:stackbuilders/nixpkgs-terraform#<template>

Note: Replace <template> with one of the templates listed above.

Inspired By

The current project structure as well as some components of the CI workflow are heavily inspired by the following projects:

• nixpkgs-python - All Python versions, kept up-to-date on hourly basis using Nix.
• nixpkgs-ruby - A Nix repository with all Ruby versions being kept up-to-date automatically.

License

MIT, see the LICENSE file.

Contributing

Do you want to contribute to this project? Please take a look at our contributing guideline to know how you can help us build it.

Aside from the contribution guidelines outlined above, this project uses semantic-release to automate version management; thus, we encourage contributors to follow the commit conventions outlined here to make it easier for maintainers to release new changes.

---

Check out our libraries | Join our team