This project practices infrastructure-as-code and uses the Terraform framework. This directory contains the infrastructure code for this project, including infrastructure for all application resources. This terraform project uses the AWS provider. It is based on the Nava platform infrastructure template.

The structure for the infrastructure code looks like this:

infra/                  Infrastructure code
  accounts/             [Root module] IaC and IAM resources
  [app_name]/           Application directory: infrastructure for the main application
  modules/              Reusable child modules
  networks/             [Root module] Account level network config (shared across all apps, environments, and terraform workspaces)

Each application directory contains the following:

  app-config/         Application-level configuration for the application resources (different config for different environments)
  build-repository/   [Root module] Docker image repository for the application (shared across environments and terraform workspaces)
  database/           [Root module] Configuration for database (different config for different environments)
  service/            [Root module] Configuration for containers, such as load balancer, application service (different config for different environments)

Details about terraform root modules and child modules are documented in module-architecture.

The infrastructure template is designed to operate on different layers:

• Account layer
• Network layer
• Build repository layer (per application)
• Database layer (per application)
• Service layer (per application)

This project has the following AWS environments:

• dev
• staging
• prod

The environments share the same root modules but will have different configurations. Backend configuration is saved as .tfbackend files. Most .tfbackend files are named after the environment. For example, the [app_name]/service infrastructure resources for the dev environment are configured via dev.s3.tfbackend. Resources for a module that are shared across environments, such as the build-repository, use shared.s3.tfbackend. Resources that are shared across the entire account (e.g. /infra/accounts) use <account name>.<account id>.s3.tfbackend.

This project relies on Make targets in the root Makefile, which in turn call shell scripts in ./bin. The shell scripts call terraform commands. Many of the shell scripts are also called by the Github Actions CI/CD.

Generally, you should use the Make targets or the underlying bin scripts, but you can call the underlying terraform commands if needed. See making-infra-changes for more details.

To set up this project for the first time (i.e., it has never been deployed to the target AWS account):

1. Install this template into an application that meets the Application Requirements
2. Configure the project (These values will be used in subsequent infra setup steps to namespace resources and add infrastructure tags.)
3. Set up infrastructure developer tools
4. Set up AWS account
5. Set up the virtual network (VPC)
6. For each application:
   1. Set up application build repository
   2. Set up application database
   3. Set up application environment
   4. Configure environment variables and secrets
   5. Set up background jobs

To get set up as a new developer on a project that has already been deployed to the target AWS account:

1. Set up infrastructure developer tools
2. Review how to make changes to infrastructure
3. Review the infrastructure style guide
4. (Optional) Set up a terraform workspace

Additional documentation can be found in the documentation directory.