TerraDagger 🗡️

An easy to understand GO library for building portables CI/CD pipelines (as code) using Dagger for your infrastructure-as-code ☁️.

TerraDagger is a GO library that provides a set of functions and patterns for building portable CI/CD pipelines (as code) for your infrastructure-as-code. It's based on the wonderful Dagger pipeline-as-code project, and heavily inspired by Terratest. The problem that TerraDagger tries to solve is to provide a simple way to run your Terraform code in a portable way, and also to provide a way to run your pipelines in a containerized way, so you can run your pipelines in any environment, and also in any CI/CD platform.

Installation 🛠️

Install it using Go get:

go get github.com/Excoriate/go-terradagger

Pre-requisites 📋

Go >= 1.18
Docker >= 20.10.7
Dagger

NOTE: For the tools used in this project, please check the Makefile, and the Taskfile files. You'll also need pre-commit installed.

Features 🎉

Portable: TerraDagger is built to be used in any CI/CD platform, and also in any environment (including your local machine).
Simple: TerraDagger is built to be simple to use, if you're familiar with Terratest, then you'll find this library very similar.
IAC Support: Supports Terraform and Terragrunt.

Getting Started 🚀

Configure the terradagger client, which under the hood, will configure the Dagger client:

td := terradagger.New(ctx, &terradagger.Options{
  Workspace: viper.GetString("workspace"),
})

Now, it's time to start the engine (Dagger). It's important to start the engine before running any command, so ensure that your Docker daemon or any compatible OCI runtime is running.

if err := td.StartEngine(); err != nil {
    return err // Handle the error properly in your code.
}

defer td.Engine.GetEngine().Close()

Terradagger has global options, and also specific terraform and terragrunt options. you can set the global options like this:

tfOptions :=
   terraformcore.WithOptions(td, &terraformcore.TfOptions{
     ModulePath:                   viper.GetString("module"),
     EnableSSHPrivateGit:          true,
     TerraformVersion:             viper.GetString("terraform-version"),
     EnvVarsToInjectByKeyFromHost: []string{"AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN"},
   })

There are many options supported, options that are meant to facilitate the use of containerized pipelines based on common use-cases, such as:

Injecting environment variables from the host to the container.
Auto-injecting the AWS credentials from the host to the container.
Forward your SSH agent to the container, so you can use your SSH keys in the container.

And then, you're good to go and run your desired Terraform commands, and chain them as you wish:

_, tfInitErr := terraform.InitE(td, tfOptions, terraform.InitOptions{})
if tfInitErr != nil {
    return tfInitErr
}

NOTE: The E suffix in the function name means that the specific terraform command will return the stdout and an error object. The variant without the E suffix will return the actual Dagger Container object, and an error object.

To see a full working example, please check the terradagger-cli that's built in this repository

Roadmap 🗓️

Add basic support for Terraform commands (init, validate, plan, apply, destroy, etc).
Add out-of-the-box support for TfLint.
Add extra commands: Validate, Format, and Import.
Add plenty of missing tests 🧪
Add support for Terragrunt.
Enrich the terragrunt API to cover all the commands supported.
Add support for Terratest.
Add official Docker images for TerraDagger.

Note: This is still work in progress, however, I'll be happy to receive any feedback or contribution. Ensure you've read the contributing guide before doing so.

Contributing

Please read our contributing guide.

Excoriate / go-terradagger