- Notifications
You must be signed in to change notification settings - Fork20
A Terragrunt frontend that allow execution of Terragrunt/Terraform through Docker
License
coveooss/tgf
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
ATerragruntfrontend that allows execution of Terragrunt/Terraform through Docker.
Table of content:
TGF is a small utility used to launch a Docker image and automatically map the current folder, your HOME folder and your current environmentvariables to the underlying container.
By default, TGF is used as a frontend forour fork of terragrunt, but it could also be used to run different endpoints.
UsingTGF ensures 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 sensitive to the version used and if one user updates to a newer version, the state files will be marked with the latest version andall other users will have to update theirTerraform version to the latest used one.
Also, tools such asAWS CLI are updated on a regular basis and people don't tend to update their version regularly, resulting in many versionsamong your users. If someone makes a script calling a new feature of theAWS api, that script may break when executed by another user that has anoutdated version.
You can installTGF using the provided GitHub Action:
steps: -uses:coveooss/tgf@main
Onmac andlinux:
You can run theget-latest-tgf.sh script to check if you have the latest version of tgf installed and install it as needed:
curl https://raw.githubusercontent.com/coveooss/tgf/main/get-latest-tgf.sh| bashOnWindows, runget-latest-tgf.ps1 with Powershell (version 7.x or more):
(Invoke-WebRequest https://raw.githubusercontent.com/coveooss/tgf/main/get-latest-tgf.ps1).Content|Invoke-Expression
This will install tgf in your current directory. Make sure to add the executable to your PATH.
TGF has multiple levels of configuration. It first looks through theAWS parameter storeunder/default/tgf using your currentAWS CLI configuration if any. There, it tries to find parameters calledconfig-location (example: bucket.s3.amazonaws.com/foo) andconfig-paths (example: my-file.json:my-second-file.json, default: TGFConfig). If it findsconfig-location, it fetches its config from that path using thego-getter library. Otherwise, it looks directly in SSM for configuration keys (ex:/default/tgf/logging-level).
Note: The SSM configuration will only be read if AWS environment variables are set, the AWS CLI is installed or the ~/.aws folder exists. If you wish to force TGF to read the SSM config and these conditions are not met, you can set theTGF_USE_AWS_CONFIG=true environment variable
TGF then looks for a file named .tgf.config or tgf.user.config in the current working folder (and recursively in any parent folders) to get its parameters. These configuration files overwrite the remote configurations.Your configuration file could be expressed inYAML orJSON.
Example of a YAML configuration file:
docker-refresh:1hlogging-level:notice
Example of a JSON configuration file:
{"docker-refresh":"1h","logging-level":"notice"}| Key | Description | Default value |
|---|---|---|
| docker-image | Identify the docker image to use | coveo/tgf |
| docker-image-version | Identify the image version | no default |
| docker-image-tag | Identify the image tag (could specify specialized version such as k8s, full) | latest |
| docker-image-build | List of Dockerfile instructions to customize the specified docker image | no default |
| docker-image-build-folder | Folder where the docker build command should be executed | no default |
| docker-refresh | Delay before checking if a newer version of the docker image is available | 1h (1 hour) |
| docker-options | Additional options to supply to the Docker command | no default |
| logging-level | Terragrunt logging level (only applies to Terragrunt entry point). Critical (0), Error (1), Warning (2), Notice (3), Info (4), Debug (5), Full (6) | Notice |
| entry-point | The program that will be automatically launched when the docker container 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 |
| environment | Allows temporary addition of environment variables | no default |
| run-before | Script that is executed before the actual command | no default |
| run-after | Script that is executed after the actual command | no default |
| alias | Allows to set short aliases for long commandsmy_command: "--ri --with-docker-mount --image=my-image --image-version=my-tag -E my-script.py" | no default |
| auto-update | Toggles the auto update check. Will only perform the update after the delay | true |
| auto-update-delay | Delay before running auto-update again | 2h (2 hours) |
| update-version | The version to update to when running auto update | Latest fetched from Github's API |
Note:The key names are not case-sensitive
It is possible to specify configuration elements that only apply on a specific os.
Example of an HCL configuration file:
docker-refresh: 1hlogging-level: noticewindows: logging-level: debuglinux: docker-refresh: 2h| section | Description |
|---|---|
| windows | Configuration that is applied only on Windows systems |
| linux | Configuration that is applied only on Linux systems |
| darwin | Configuration that is applied only on OSX systems |
| ix | Configuration that is applied only on Linux or OSX systems |
> tgf -Husage: tgf [<flags>]DESCRIPTION:TGF (terragrunt frontend) is a Docker frontend for terragrunt/terraform. It automatically maps your current folder, your HOMEfolder, your TEMP folder as well of most environment variables to the docker process. You can add -D to your command to get theexact docker command that is generated.It then looks in your current folder and all its parents to find a file named '.tgf.config' to retrieve the default configuration.If not all configurable values are satisfied and you have an AWS configuration, it will then try to retrieve the missing elementsfrom the AWS Parameter Store under the key '/default/tgf'.Configurable values are: - docker-image - docker-image-version - docker-image-tag - docker-image-build - docker-image-build-folder - docker-image-build-tag - logging-level - entry-point - docker-refresh - docker-options - recommended-image-version - required-image-version - tgf-recommended-version - environment - run-before - run-after - alias - update-version - auto-update-delay - auto-updateFull documentation can be found at https://github.com/coveooss/tgf/blob/main/README.mdCheck for new version at https://github.com/coveooss/tgf/releases/latest.Any docker image could be used, but TGF specialized images could be found at: https://hub.docker.com/r/coveo/tgf/tags.Terragrunt documentation could be found at https://github.com/coveo/terragrunt/blob/main/README.md (Coveo fork)Terraform documentation could be found at https://www.terraform.io/docs/index.html.SHORTCUTS:You can also use shortcuts instead of using the long argument names (first letter of each word).Ex: --li ==> --local-image --iv=2.0 ==> --image-version=2.0IMPORTANT:Most of the tgf command line arguments are in uppercase to avoid potential conflict with the underlying command. If any of the tgfarguments conflicts with an argument of the desired entry point, you must place that argument after -- to ensure that they are notinterpreted by tgf and are passed to the entry point. Any non conflicting argument will be passed to the entry point wherever it islocated on the invocation arguments. tgf ls -- -D # Avoid -D to be interpreted by tgf as --debugIt is also possible to specify additional arguments through environment variable TGF_ARGS.VERSION: v1.28.13-29-gc429fcaAUTHOR: CoveoFlags: -H, --[no-]help-tgf Show context-sensitive help (also try --help-man) ($TGF_HELP_TGF) --image=coveo/tgf Use the specified image instead of the default one ($TGF_IMAGE) --image-version=version Use a different version of docker image instead of the default one ($TGF_IMAGE_VERSION) -T, --tag=latest Use a different tag of docker image instead of the default one ($TGF_TAG) --[no-]local-image If set, TGF will not pull the image when refreshing ($TGF_LOCAL_IMAGE) --[no-]get-image-name Just return the resulting image name ($TGF_GET_IMAGE_NAME) --[no-]refresh-image Force a refresh of the docker image ($TGF_REFRESH_IMAGE) -E, --entrypoint=terragrunt Override the entry point for docker ($TGF_ENTRYPOINT) --[no-]current-version Get current version information ($TGF_CURRENT_VERSION) --[no-]all-versions Get versions of TGF & all others underlying utilities ($TGF_ALL_VERSIONS) -L, --logging-level=<level> Set the logging level (panic=0, fatal=1, error=2, warning=3, info=4, debug=5, trace=6, full=7) ($TGF_LOGGING_LEVEL) -D, --[no-]debug Print debug messages and docker commands issued ($TGF_DEBUG) --[no-]aws-debug Activate debug logging for the AWS SDK. This will print requests & responses made by the AWS SDK. ($TGF_AWS_DEBUG) -F, --[no-]flush-cache Invoke terragrunt with --terragrunt-update-source to flush the cache ($TGF_FLUSH_CACHE) --[no-]interactive ON by default: Launch Docker in interactive mode ($TGF_INTERACTIVE) --[no-]docker-build ON by default: Enable docker build instructions configured in the config files ($TGF_DOCKER_BUILD) --[no-]home Enable mapping of the home directory ($TGF_HOME) --[no-]temp ON by default: Map the temp folder to a local folder (Deprecated: Use --temp-location host and --temp-location none) ($TGF_TEMP) --temp-location=folder Determine where the temporary work folder 'tgf' inside the docker image is mounted: volume: Mounts the work folder in the docker volume named “tgf”. The volume is created if it doesn't exist. host: Mounts the work folder in a directory on the host. none: The work folder is not mounted and is private to the docker container. ($TGF_TEMP_LOCATION) --mount-point=<folder> Specify a mount point for the current folder ($TGF_MOUNT_POINT) --[no-]prune Remove all previous versions of the targeted image ($TGF_PRUNE) --docker-arg=<opt> ... Supply extra argument to Docker ($TGF_DOCKER_ARG) --[no-]with-current-user Runs the docker command with the current user, using the --user arg ($TGF_WITH_CURRENT_USER) --[no-]with-docker-mount Mounts the docker socket to the image so the host's docker api is usable ($TGF_WITH_DOCKER_MOUNT) --[no-]ignore-user-config Ignore all tgf.user.config files ($TGF_IGNORE_USER_CONFIG) --[no-]aws ON by default: Use AWS Parameter store to get configuration ($TGF_AWS) -P, --profile=<AWS profile> Set the AWS profile configuration to use ($TGF_PROFILE) --ssm-path=<path> Parameter Store path used to find AWS common configuration shared by a team ($TGF_SSM_PATH) --config-files=<files> Set the files to look for (default: TGFConfig) ($TGF_CONFIG_FILES) --config-location=<path> Set the configuration location ($TGF_CONFIG_LOCATION) --[no-]config-dump Print the TGF configuration and exit ($TGF_CONFIG_DUMP) --[no-]update Run auto update script ($TGF_UPDATE)Example:
> tgf --current-versiontgf v1.22.0Returns the current version of the tgf tool
> tgf -- --versionterragrunt version v1.2.0Returns the version of the default entry point (i.e.Terragrunt), the --version located after the -- instructs tgf to pass this argumentto the desired entry point
> tgf -E terraform -- --versionTerraform v0.11.8Returns the version ofTerraform since we specified the entry point to be terraform.
- Terraform
- Terragrunt
- Go Template
- Shells & tools
shopenssl
All tools included incoveo/tgf:base plus:
- Python (2 and 3)
- Ruby
- AWS CLI
- jq
- Terraforming
- Tflint
- Terraform-docs
- Terraform Quantum Provider
- Shells
bashzshfish
- Tools & editors
vimnanozipgitmercurial
All tools included incoveo/tgf plus:
All tools included incoveo/tgf:aws plus:
kubectlhelm
All tools included in the other images plus:
- AWS Tools for Powershell
- Oh My ZSH
- Shells
powershell
> tgf planInvoketerragrunt plan (which will invoketerraform plan) after doing theterragrunt relative configurations.
> tgf apply -var env=devInvoketerragrunt apply (which will invoketerraform apply) after doing theterragrunt relative configurations. You can pass any argumentsthat are supported byterraform.
> tgf plan-allInvoketerragrunt plan-all (which will invoketerraform plan on the current folder and all sub folders).Terragrunt allows xxx-all operations to beexecuted according to dependencies that are defined by thedependencies statements.
> tgf -E aws s3 lsInvokeAWS CLI as entry point and list all s3 buckets
> tgf -E fishStart a shellfish in the current folder
> tgf -E my_command -i my_image:latestInvokesmy_command in your own docker image. As you can see, you can do whatever you need to withtgf. It is not restricted to only the pre-packagedDocker images, you can use it to run any program in any Docker images. Your imagination is your limit.
About
A Terragrunt frontend that allow execution of Terragrunt/Terraform through Docker