🧩 Terraform AWS ☁️ Stacks 📚

An easy to understand, opinionated terraform composable set of Stack-composite modules that solves real-world problems ☁️while using Stacks.

---

Table of Contents

1. About The Module
2. Module documentation
   1. Capabilities
   2. Getting Started
   3. Roadmap
   4. Module standard structure
3. Developer Experience
   1. Configuring AWS credentials for local development
   2. Running common development actions
   3. Running tests
4. Contributions
5. License
6. Contact

About The Module

This repository is a collection (always evolving) of terraform modules that I use in my day-to-day work. It's a collection of modules that I use to solve real-world problems, and I'm sharing them with the community. I hope you find them useful. The collection of modules placed here are stack-composite modules, that implement specific functionality as ready-to-use architectures for common use-cases. Common uses cases refers to:

• Network: VPC, Subnets, NAT Gateways, Internet Gateways, Route Tables, etc.
• Restful services: ALB, on top of an Elastic Container service, with the necessary settings to allow a quick deployment
• etc.

---

Module documentation

The documentation is automatically generated by terraform-docs, and it's available in the module's README.md file.

Capabilities

Module	Status	Description
stack-aws-dns-zone-multi-account	Stable ✅	A stack-composite module that implements a multi-account DNS zone delegation.
stack-aws-alb-http	Stable ✅	Stack-composite module that implement a common ALB/Ingress architecture, for fronting a backend such as an ECS-based (micro?) service, API or equivalent.
stack-secrets-manager	Stable ✅	Stack-composite that implement a common set of actions on top of an AWS secret, including replication, permissions, etc..
stack-auth (cognito)	Stable ✅	Stack-composite that implement a full set of capabilities to perform authorization/authentication using Cognito, and SES (for email verification, password recoveryu, etc.).

Getting Started

Check the example recipes 🥗 here

Roadmap

• 👨🏻‍💻 Add built-in ACM certificates into the stack-alb-http module

Module standard structure

The module's relevant components, structure and "skeleton" is described below:

├── README.md
├── TaskFile.yml
├── docs
│   └── contribution_guidelines.md
├── examples
│   ├── README.md
│   ├── TaskFile.yml
│   └── default
│       └── basic
│           ├── README.md
│           ├── config
│           │   └── fixtures.tfvars
│           ├── main.tf
│           ├── providers.tf
│           ├── variables.tf
│           └── versions.tf
├── modules
│   ├── TaskFile.yml
│   └── default
│       ├── README.md
│       ├── data.tf
│       ├── locals.tf
│       ├── main.tf
│       ├── outputs.tf
│       ├── variables.tf
│       └── versions.tf
├── pre-commit-config-githubactions.yaml
└── tests
    ├── README.md
    ├── TaskFile.yml
    └── default
        ├── integration
        │   ├── default_basic_integration_test.go
        │   ├── go.mod
        │   ├── go.sum
        │   └── target
        │       └── basic
        │           └── main.tf
        └── unit
            ├── default_basic_unit_test.go
            ├── go.mod
            ├── go.sum
            └── target
                └── basic
                    └── main.tf

Where:

• ⚡️Modules: refers to the actual module's directory. Where the .tf files reside. Each subdirectory is a module.
• ⚡️Examples: refers to the examples directory, where the examples recipes lives. These are also used for testing the infrastructure using Terratest. For its specific documentation, query this link
• ⚡️Tests: refers to the tests directory, where the tests recipes lives. These are also used for testing the infrastructure using Terratest. For its specific documentation, query this link

Developer Experience

Some tools that this repo uses:

• 🧰 Terraform — strongly recommended the latest versions
• 🧰 Go — justified mostly for Terratest
• 🧰 TaskFile — for the automation of the tasks.

NOTE: For automation during the development process, I use precommit, which is a framework for managing and maintaining multi-language pre-commit hooks. It's a great tool, and I highly recommend it. All the hooks required are installed by this script. It's recommended though to run it through the TaskFile task pre-commit-init.

To initialize your pre-commit configuration, and ensure all the hooks are installed, run the following command:

task pre-commit-init

To run these hooks against all the files, you can use the following Task command:

task pre-commit

Configuring AWS credentials for local development

For sure you've seen that in the main Taskfile, there's a task called gen-env-aws. That task aims to generate a proper .env.<env>.aws dotEnv file which is used by the TaskFile.yml tasks. If you have a proper AWS credentials file, you can run the following command:

task gen-env-aws

In simple terms, that tasks (which runs a shell script) scan your pre-existing AWS profiles, and generate the .env.<env>.aws file for you. When it's generated, running a task that wraps a terraform command, will use the generated .env.<env>.aws file to set the proper AWS credentials. For example:

# dev refers to the environment selected, which's how the file is also named. E.g.: env.dev.aws
ENV=dev task module-plan

Running common actions for local development

Run unit tests (wrapping Terratest):

# If you want to list the available tasks.
task list
# Run the unit tests.
task test-unit

Run integration tests — if exists (wrapping Terratest):

# If you want to list the available tasks.
task list
# Run the unit tests.
task test-integration

Run all the configured pre-commit hooks (forcing them to run on all files):

task pre-commit

Run a vanilla terraform plan over the example/basic (recipe) example:

# No arguments are required, since it's using its defaults: example as the module's name, and basic as its recipe's name.
task recipe-plan

Tests

See the detailed documentation here.

---

Module Versioning

This Module follows the principles of Semantic Versioning (SemVer).

Given a version number MAJOR.MINOR.PATCH, we increment the:

1. MAJOR version when we make incompatible changes,
2. MINOR version when we add functionality in a backwards compatible manner, and
3. PATCH version when we make backwards compatible bug fixes.

Backwards compatibility in 0.0.z and 0.y.z version

• Backwards compatibility in versions 0.0.z is not guaranteed when z is increased. (Initial development)
• Backwards compatibility in versions 0.y.z is not guaranteed when y is increased. (Pre-release)

Contributing

Contributions are always encouraged and welcome! ❤️. For the process of accepting changes, please refer to the CONTRIBUTING.md file, and for a more detailed explanation, please refer to this guideline here.

License

This module is licensed under the Apache License Version 2.0, January 2004. Please see LICENSE for full details.

Contact

• 📧 Email: Alex T.
• 🧳 Linkedin: Alex T.

made/with ❤️ 🤟