Skip to main content

Overview

How modules are structured​

The code in the module repos are organized into three primary folders:

  1. modules: The core implementation code. All of the modules that you will use and deploy are defined within. For example to ECS cluster module in the terraform-aws-ecs repo in modules/ecs-cluster.

  2. examples: Sample code that shows how to use the modules in the modules folder and allows you to try them out without having to write any code: cd into one of the folders, follow a few steps in the README (e.g. run terraform apply), and you’ll have a fully working module up and running. In other words, this is executable documentation.

  3. test: Automated tests for the code in modules and examples.

We follow Hashicorp's Standard Model Structure for our files (main.tf, variables.tf, outputs.tf). In the variables.tf file we always put the required variables at the top of the file, followed by the optional variables. Although there are often a lot of ways to configure our modules, we set reasonable defaults and try to minimize the effort required to configure the modules to the most common use cases.

How services are structured​

The code in the terraform-aws-service-catalog repo is organized into three primary folders:

  1. modules: The core implementation code of this repo. All the services that you will use and deploy are defined within, such as the EKS cluster service in modules/services/eks-cluster.

  2. examples: Sample code that shows how to use the services in the modules folder and allows you to try the services out without having to write any code: you cd into one of the folders, follow a few steps in the README (e.g., run terraform apply), and you’ll have fully working infrastructure up and running. In other words, this is executable documentation. Note that the examples folder contains two sub-folders:

    1. for-learning-and-testing: Example code that is optimized for learning, experimenting, and testing, but not direct production usage. Most of these examples use Terraform directly to make it easy to fill in dependencies that are convenient for testing, but not necessarily those you’d use in production: e.g., default VPCs or mock database URLs.

    2. for-production: Example code optimized for direct usage in production. This is code from the Gruntwork Reference Architecture, and it shows you how we build an end-to-end, integrated tech stack on top of the Gruntwork Service Catalog. To keep the code DRY and manage dependencies between modules, the code is deployed using Terragrunt. However, Terragrunt is NOT required to use the Gruntwork Service Catalog: you can alternatively use vanilla Terraform or Terraform Cloud / Enterprise, as described here.

    3. Not all modules have a for-production example, but you can still create a production-grade configuration by using the template provided in this discussion question, How do I use the modules in terraform-aws-service-catalog if there is no example?.

  3. test: Automated tests for the code in modules and examples.

Tools used in Library​

OpenTofu Support

Gruntwork Library actively supports OpenTofu. If you encounter any issues using the library with OpenTofu please reach out to support@gruntwork.io.

Gruntwork Library has been created using the following tools:

  1. Terraform. The Library contains nearly 300 Terraform modules that cover a range of common use cases in AWS. All library modules can be used with vanilla Terraform, Terragrunt, or third-party Terraform pipeline tools such as Terraform Cloud and Terraform Enterprise.

  2. Packer. The Library defines machine images (e.g., VM images) using Packer, where the main use case is building Amazon Machine Images (AMIs) that run on EC2 instances whose configuration is all defined in code. Once you’ve built an AMI, you can use Terraform to deploy it into AWS.

  3. Terratest. All modules are functionally validated with automated tests written using Terratest.