coveo/tgf repository overview

⁠TGF

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

Table of content:

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

⁠Description

TGF allows 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.12.1/tgf_1.12.1_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.12.1/tgf_1.12.1_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.12.1/tgf_1.12.1_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

Note: The key names are not case sensitive

⁠TGF Invocation

> tgf
usage: tgf [<flags>]

tgf v1.12.1, 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=ENTRYPOINT  Override the entry point for docker whish is terragrunt by default
  -i, --image=IMAGE            Use the specified image instead of the default one
  -d, --debug                  Print the docker command issued
  -t, --tag=TAG                Use a different tag on docker image instead of the default one
  -r, --refresh                Force a refresh of the docker image
  -v, --version                Get the current version of tgf

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.12.1

Returns the current version of the tgf tool

> tgf -- --version
terragrunt version v0.12.24.01(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.