TGF

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

Table of content:

• Description
• Configuration
• Invocation arguments
• Images
• Usage
• Development

Description

TGF is a small utility used to launch a Docker image and automatically map the current folder, your HOME folder and your current environment variables to the underlying container.

By default, TGF is used as a frontend for terragrunt, but it could also be used to run different endpoints.

Why use TGF

Using TGF ensure that all your users are using the same set of tools to run infrastructure configuration even if they are working on different environments (linux, Microsoft Windows, Mac OSX, etc).

Terraform is very sensible to the version used and if one user update to a newer version, the state files will be marked with the latest version and all other user will have to update their Terraform version to the latest used one.

Also, tools such as AWS CLI are updated on a regular basis and people don't tend to update their version regularly, resulting in many different version among your users. If someone make a script calling a new feature of the AWS api, that script may break when executed by another user that has an outdated version.

Installation

Choose the desired version according to your OS here, unzip it, make tgf executable chmod +x tgf and put it somewhere in your PATH.

or install it through command line:

On OSX:

curl -sL https://github.com/coveo/tgf/releases/download/v1.13.2/tgf_1.13.2_macOS_64-bits.zip | bsdtar -xf- -C /usr/local/bin && chmod +x /usr/local/bin/tgf

On Linux:

curl -sL https://github.com/coveo/tgf/releases/download/v1.13.2/tgf_1.13.2_linux_64-bits.zip | gzip -d > /usr/local/bin/tgf && chmod +x /usr/local/bin/tgf

On Windows with Powershell:

Invoke-WebRequest https://github.com/coveo/tgf/releases/download/v1.13.2/tgf_1.13.2_windows_64-bits.zip -OutFile tgf.zip

Configuration

TGF looks for a file named .tgf.config in the current working folder (and recursively in any parent folders) to get its parameters. If some parameters are missing, it tries to find the remaining configuration through the AWS parameter store under /default/tgf using your current AWS CLI configuration if any.

Your configuration file could be expressed in any of the YAML, JSON or Terraform HCL declarative language.

Example of YAML configuration file:

docker-image: coveo/tgf
docker-refresh: 1h
logging-level: notice
entry-point: terragrunt

Example of HCL configuration file:

docker-image = "coveo/tgf"
docker-refresh = "1h"
logging-level = "notice"
entry-point = "terragrunt"

Example of JSON configuration file:

"docker-image": "coveo/tgf"
"docker-refresh": "1h"
"logging-level": "notice"
"entry-point": "terragrunt"

Configuration keys

Key	Description	Default value
docker-image	Identify the docker image (with tag if necessary) to use	coveo/tgf
docker-refresh	Delay before checking if a newer version of the docker image is available	1h (1 hour)
docker-debug	Tell tgf to display the detailed Docker command prior to execute it	0
logging-level	Terragrunt logging level (only apply to Terragrunt entry point). Critical (0), Error (1), Warning (2), Notice (3), Info (4), Debug (5)	Notice
entry-point	The program that will be automatically launched when the docker starts	terragrunt
tgf-recommended-version	The minimal tgf version recommended in your context (should not be placed in .tgf.config file)	no default
recommended-image	The tgf image recommended in your context (should not be placed in .tgf.config file)	no default

Note: The key names are not case sensitive

TGF Invocation

> tgf
usage: tgf [<flags>]

tgf v1.13.2, a docker frontend for terragrunt. Any parameter after -- will be directly sent to the command identified by entrypoint.

Flags:
  -h, --help                   Show context-sensitive help (also try --help-long and --help-man).
  -e, --entrypoint=terragrunt  Override the entry point for docker
  -i, --image=coveo/tgf        Use the specified image instead of the default one
  -t, --tag=latest             Use a different tag on docker image instead of the default one
  -p, --profile=""             Set the AWS profile configuration to use
  -d, --debug                  Print the docker command issued
  -r, --refresh                Force a refresh of the docker image
  -v, --version                Get the current version of tgf
  -l, --logging=<level>        Set the logging level (critical=0, error=1, warning=2, notice=3, info=4, debug=5)
      --no-home                Disable the mapping of the home directory

If any of the tgf arguments conflicts with an argument of the desired entry point, you must place that argument after -- to ensure that they are not interpreted by tgf and are passed to the entry point. Any non conflicting argument will be passed to the entry point wherever it is located on the invocation arguments.

Example:

> tgf --version
v1.13.2

Returns the current version of the tgf tool

> tgf -- --version
terragrunt version v0.12.24.10(Coveo)

Returns the version of the default entry point (i.e. Terragrunt), the --version located after the -- instructs tgf to pass this argument to the desired entry point

> tgf -e terraform -- --version
Terraform v0.9.11

Returns the version of Terraform since we specified the entry point to be terraform.

Default Docker images

Base image: coveo/tgf.base (based on Alpine)

• Terraform
• Terragrunt
• Go Template
• Shells
  • sh

Default image: coveo/tgf (based on Alpine)

All tools included in coveo/tgf.base plus:

• Python (2 and 3)
• Ruby
• AWS CLI
• jq
• Terraforming
• Tflint
• Terraform Quantum Provider
• Shells
  • bash
  • zsh
  • fish

Full image: coveo/tgf.full (based on Ubuntu)

All tools included in coveo/tgf plus:

• AWS Tools for Powershell
• Oh My ZSH
• Shells
  • powershell

Usage

As Terragrunt front-end

> tgf plan

Invoke terragrunt plan (which will invoke terraform plan) after doing the terragrunt relative configurations.

> tgf apply -var env=dev

Invoke terragrunt apply (which will invoke terraform apply) after doing the terragrunt relative configurations. You can pass any arguments that are supported by terraform.

> tgf plan-all

Invoke terragrunt plan-all (which will invoke terraform plan on the current folder and all sub folders). Terragrunt allows xxx-all operations to be executed according to dependencies that are defined by the dependencies statements.

Other usages

> tgf -e aws s3 ls

Invoke AWS CLI as entry point and list all s3 buckets

> tgf -e fish

Start a shell fish in the current folder

> tgf -t full -e powershell

Starts a powershell in the current working directory.

> tgf -e my_command -i my_image:latest

Invokes my_command in your own docker image. As you can see, you can do whatever you need to with tgf. It is not restricted to only the pre-packaged Docker images, you can use it to run any program in any Docker images. Your imagination is your limit.

Development

Build are automatically launched on tagging.

Tags with format 0.00 automatically launch a Docker images build that are available through Docker Hub. Tags with format v0.00 automatically launch a new release on Github for the TGF executable.