How do I install TGF on a Mac with Rancher Desktop?

Set the DOCKER_HOST environment variable to 'unix://$HOME/.rd/docker.sock' in your shell config file, then run the get-latest-tgf.sh script. This is necessary because Rancher Desktop uses a different Docker socket location than standard Docker Desktop.

TGF vs using plain Docker for Terraform: which should I choose?

TGF automates folder mapping, env vars, and image management, making it easier for teams to ensure consistency. Choose plain Docker if you need full control over container config, but TGF is better for standardizing workflows across a team with mixed environments.

Can TGF work with Google Cloud or Azure instead of AWS?

Yes, TGF can run any Docker image, so you can use images with GCP or Azure CLI tools. However, the default configuration and examples are AWS-centric, so you'll need to customize the Docker image and entry points for other clouds.

How to create a custom Docker image for TGF?

Use the docker-image-build key in your config with Dockerfile instructions, or set docker-image to your custom image. TGF will build or pull the image as configured, and you can specify it with the --image flag and run custom entry points with -E.

What should I do if TGF fails to pull a Docker image?

Check your network and Docker daemon status. Use --local-image to skip pulling, or adjust docker-refresh in config. Ensure the image name and version are correct, and consider using a local image cache or custom build.

Does TGF support Terraform workspaces or remote backends?

Yes, TGF runs Terraform inside Docker, so it supports workspaces and remote backends like Terraform Cloud. Pass necessary credentials via environment variables or mounted files, as TGF maps the current folder and env vars to the container.

Open-Awesome

tgf

MITGov1.30.1

A Docker frontend for Terragrunt and Terraform that ensures consistent tooling across environments.

GitHub

109 stars20 forks0 contributors

What is tgf?

TGF is a Docker frontend for Terragrunt and Terraform that wraps infrastructure commands in containers to guarantee consistent tool versions across team members. It solves the problem of Terraform state file version mismatches and outdated CLI tools by running everything inside a controlled Docker environment.

Target Audience

Infrastructure engineers and DevOps teams managing Terraform/Terragrunt projects who need to ensure consistent execution environments across Windows, macOS, and Linux workstations.

Value Proposition

Developers choose TGF because it eliminates 'works on my machine' issues in infrastructure code, provides a unified toolset via Docker images, and offers flexible configuration without requiring everyone to manually manage tool versions.

Overview

A Terragrunt frontend that allow execution of Terragrunt/Terraform through Docker

Use Cases

Best For

Ensuring Terraform version consistency across a distributed team
Running Terragrunt commands in a reproducible Docker environment
Managing infrastructure code on mixed OS environments (Windows, macOS, Linux)
Automating AWS CLI and other tooling versions for scripts
Providing a standardized shell environment for infrastructure development
Extending Terraform workflows with custom Docker images and entry points

Not Ideal For

Environments where Docker cannot be installed or run, such as air-gapped systems or CI/CD platforms without container support
Teams that have already standardized tool versions using managers like tfenv or asdf and prefer minimal overhead
Projects requiring deep integration with host system tools or GUIs that are complex to expose through Docker mounts
Use cases where low-latency execution is critical, as container startup adds noticeable delay

Pros & Cons

Pros

Version Consistency Guaranteed

TGF runs Terraform, Terragrunt, and AWS CLI inside Docker containers, ensuring all team members use identical tool versions and eliminating state file conflicts, as highlighted in the 'Why use TGF' section.

Cross-Platform Execution

By leveraging Docker, TGF provides the same behavior on Linux, Windows, and macOS, making infrastructure code portable across different developer machines, as stated in the multi-platform support feature.

Flexible Configuration Management

Supports YAML, JSON, HCL configs, remote sources like S3, and AWS Parameter Store, with OS-specific sections for fine-grained control, detailed in the Configuration section.

Extensible Beyond Terraform

Can run any program in any Docker image, from AWS CLI to custom scripts, allowing teams to standardize diverse tooling environments, exemplified in the 'Other usages' examples.

Cons

Mandatory Docker Dependency

TGF requires a functioning Docker installation and daemon, adding setup complexity and making it unusable in environments where Docker is not supported, as it's core to its operation.

Complex Configuration Hierarchy

The multi-pass configuration system with local files, remote sources, and AWS integration can be difficult to debug and manage, especially with bootstrap and config passes outlined in the README.

Reliance on Coveo's Ecosystem

Default images use Coveo's forks of tools like Terragrunt and the AWS provider, which may lag behind upstream updates or introduce compatibility issues, as noted in the Docker images section.

Containerization Overhead

Running commands inside Docker containers adds latency due to image pulls and container startup, which can slow down iterative development workflows, despite the docker-refresh setting.

Frequently Asked Questions

Related Projects

terraformer

CLI tool to generate terraform files from existing infrastructure (reverse Terraform). Infrastructure to Code

Stars14,559

Forks1,836

Last commit4 months ago

$Infracost$ Infracost

Cloud cost intelligence for engineers, AI coding agents, and CI/CD 💰📉 Shift FinOps Left!

Stars12,413

Forks679

Last commit21 days ago

Terragrunt

Terragrunt is a flexible orchestration tool that allows Infrastructure as Code written in OpenTofu/Terraform to scale.

Terraform Pull Request Automation

Stars9,200

Forks1,304