AWS Organizations "PoC" Configuration

This is a proof-of-concept Terragrunt configuration repository for a hypothetical "poc" organization on Amazon Web Services that follows Amazon's recommendations for organizing environments using multiple accounts.

This repository was generated from the terragrunt-aws template and is automatically kept synchronized with new releases of the template.

Features

• Hierarchically defined configurations via terragrunt.yml files to overcome the single-include limitation and keep Terragrunt configurations as "DRY" as possible.
• TFLint integration to ensure that all Terraform modules in this repository meet basic quality standards.
• Automatically generated Terraform module documentation via Terraform-Docs.
• Automated tests for Terraform modules via Terratest and executable examples.
• Automatically updated dependency graphs for Terragrunt configurations.
• GitHub workflows to validate pull requests, deploy configuration changes, create releases, and to automate miscellaneous maintenance chores.
• commitlint configuration to ensure that all commits follow the Conventional Commits specification, so that semantically versioned releases can be created automatically.

Usage

Prerequisites for development

• tfenv and a compatible version of Terraform installed via tfenv install
• tgenv and a compatible version of Terragrunt installed via tgenv install
• AWS CLI configured to grant at least developer-level access to organization resources
• GNU Make (already comes preinstalled on macOS), or a compatible implementation

Typical development workflow

1. Clone the configuration repository on your local machine.

2. Change the configuration and verify your changes using make plan, or apply them directly using make apply.

   You can optionally pass a paths=<patterns> argument to the make command in order to run Terragrunt in a subset of directories. See the Makefile for details on how the paths variable is handled.

   The default value of the paths variable will target only configurations which can be modified by IAM users with developer-level access in the organization.

3. Commit and push your changes to a branch and open a pull request. Make sure to read the contributing guide, so that the pull request will be ready to be merged after review.

4. Wait for all status checks to complete, review execution plans and merge the pull request to apply any pending changes to non-production resources.

5. If you made any changes to production configurations, wait for the release pull request to be created and review its Terraform execution plan.

6. Merge the release pull request to apply any pending changes to production resources.

Terragrunt configuration conventions

These are the top-level conventions which apply to all Terragrunt configurations in this repository. Most subdirectories in the configuration directory hierarchy will augment these conventions in some way via terragrunt.yml files. For more details on this approach, and the recognized attributes in terragrunt.yml files, see the documentation.

Single parent terragrunt.hcl file

This repository provides a single parent terragrunt.hcl file which is included by all child terragrunt.hcl files via an include block such as the following:

include {
  path = find_in_parent_folders()
}

The parent terragrunt.hcl is flexible enough to provide terraform and remote_state blocks, as well as an inputs attribute which will normally be directly suitable for any child terragrunt.hcl file in this repository. The only additional statements in a child terragrunt.hcl file should be dependency blocks and configuration-specific inputs.

The following automatically generated graph shows the dependencies among all Terragrunt configurations which include the parent terragrunt.hcl file:

Terraform root module source

The top-level terragrunt.yml file specifies that all Terraform root modules should be located under the modules directory in this repository. The root module naming convention is further refined by additional terragrunt.yml files in the configuration directory hierarchy.

Terraform root module inputs

The following inputs are provided to every Terraform root module via TF_VAR_ environment variables:

• git_branch (string): The name of the currently checked out Git branch.
• git_commit (string): The SHA-1 hash of the latest commit on the currently checked out Git branch.
• git_repository (string): The URL of the origin remote in the Git repository configuration.
• platform (string): The name of the first subdirectory which leads to the child terragrunt.hcl file. The value can be either aws, or examples.
• root_dir (string): The absolute path of the directory which contains the parent terragrunt.hcl file.
• terraform_remote_state_backend (string): The name of the Terraform remote state for the current Terragrunt configuration.
• terraform_remote_state_config (object(any)): The configuration of the Terraform remote state backend for the current Terragrunt configuration.

Documentation

The docs directory contains the reference documentation for this Terragrunt configuration repository.

Changelog

All notable changes to this project will be documented in the CHANGELOG.md file.

Contributing

See the file CONTRIBUTING.md for contribution guidelines.

License

MIT License