Terraform Infrastructure

Terraform is an open-source infrastructure as code software tool that enables you to safely and predictably create, change, and improve infrastructure.

The Terraform infrastructure generator creates a Terraform infrastructure project. The generated application includes security best practices through Checkov security checks.

Usage

Generate a Terraform Project

You can generate a new Terraform project in two ways:

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - terraform#project
5. Fill in the required parameters
   • name: tf-infra
6. Click Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=tf-infra

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=tf-infra

npm

npx nx g @aws/nx-plugin:terraform#project --name=tf-infra

bun

bunx nx g @aws/nx-plugin:terraform#project --name=tf-infra

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

npm

npx nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

bun

bunx nx g @aws/nx-plugin:terraform#project --name=tf-infra --dry-run

Options

Parameter	Type	Default	Description
name Required	string	-	The name of the project.
type	string	application	Whether this is a terraform lib (re-usable modules) or app (deployable).
directory	string	packages	The directory of the new project.
subDirectory	string	-	The sub directory the project is placed in. By default this is the project name.

Generator Output

The generator creates different file structures depending on the project type:

Application Type

For application projects (--type=application), the generator creates a complete Terraform application with remote state management:

• Directorysrc

  • main.tf Main Terraform configuration file
  • providers.tf Provider configuration with S3 backend
  • variables.tf Input variable definitions
  • outputs.tf Output value definitions
  • Directoryenv Environment-specific variable files

    • dev.tfvars Development environment variables
• Directorybootstrap Bootstrap configuration for remote state

  • main.tf S3 bucket and policies for state storage
  • providers.tf AWS provider configuration
  • variables.tf Bootstrap variable definitions
• project.json Project configuration and build targets

Shared Terraform Modules

The generator also creates a packages/common/terraform library which initially just adds a metrics module (creates an empty Cloudformation stack with metadata) that is automatically instrumented so that the nx-plugin-for-aws team can track usage metrics.

Library Type

For library projects (--type=library), the generator creates a simpler structure for reusable Terraform modules:

• Directorysrc

  • main.tf Main Terraform module file
• project.json Project configuration and build targets

Application vs Library

Application projects include full deployment capabilities with remote state management, while library projects are designed for creating reusable Terraform modules that can be consumed by other projects.

Implementing your Terraform Infrastructure

You can start writing your Terraform infrastructure inside src/main.tf, for example:

src/main.tf

locals {
  account_id = data.aws_caller_identity.current.account_id
  aws_region = data.aws_region.current.id
}

resource "null_resource" "print_info" {
  # triggers = {
  #   always_run = timestamp()
  # }

  provisioner "local-exec" {
    command = "echo 'AWS Region: ${local.aws_region}, AWS Account: ${local.account_id}, Environment: ${var.environment}'"
  }
}

# Declare your infrastructure here
resource "aws_s3_bucket" "my_bucket" {
  bucket = "my-unique-bucket-name"
}

Cross project dependencies

If you wanted to execute a module from a seperate project (lib), you could do so as follows:

module "lib_module" {
  source = "../../path/to/my-lib/src"
}

This will automatically update the Nx graph to add a dependency between your consuming application and your lib.

Environment Configuration

Configure environment-specific variables in the src/env/*.tfvars files.

To add new environments, create a new src/env/<environment>.tfvars file with the environment-specific variables and add new entries for apply, destroy, init, plan in the project.json for the new env configuration. For example, let’s assume we want to add a prod env:

src/env/prod.tfvars

# Production environment variables
environment = "prod"
region      = "us-west-2"

project.json

{
  "targets": {
        "apply": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "command": "terraform apply ../../../dist/packages/infra/terraform/dev.tfplan"
                },
                "prod": {
                    "command": "terraform apply ../../../dist/packages/infra/terraform/prod.tfplan"
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd": "{projectRoot}/src"
            },
            "dependsOn": ["plan"]
        },
        "destroy": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "command": "terraform destroy -var-file=env/dev.tfvars"
                },
                "prod": {
                    "command": "terraform destroy -var-file=env/prod.tfvars"
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd":"{projectRoot}/src"
            },
            "dependsOn": ["init"]
        },
        "init": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "command": "terraform init -reconfigure -backend-config=\"region=$(aws configure get region)\" -backend-config=\"bucket=$(aws sts get-caller-identity --query Account --output text)-tf-state-$(aws configure get region)\" -backend-config=\"key=my-scope-my-project/dev/terraform.tfstate\""
                },
                "prod": {
                    "command": "terraform init -reconfigure -backend-config=\"region=$(aws configure get region)\" -backend-config=\"bucket=$(aws sts get-caller-identity --query Account --output text)-tf-state-$(aws configure get region)\" -backend-config=\"key=my-scope-my-project/prod/terraform.tfstate\""
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd": "{projectRoot}/src"
            }
        },
        "plan": {
            "executor": "nx:run-commands",
            "defaultConfiguration": "dev",
            "configurations": {
                "dev": {
                    "command": "terraform plan -var-file=env/dev.tfvars -out=../../../dist/packages/infra/terraform/dev.tfplan"
                },
                "prod": {
                    "command": "terraform plan -var-file=env/dev.tfvars -out=../../../dist/packages/infra/terraform/prod.tfplan"
                }
            },
            "options": {
                "forwardAllArgs": true,
                "cwd": "{projectRoot}/src"
            },
            "dependsOn": ["init"]
        }
    }
}

Default Environment

By default, all targets assume dev environment, however you can target a specific environment as follows:

• pnpm
• yarn
• npm
• bun

pnpm nx apply tf-infra --configuration=prod

yarn nx apply tf-infra --configuration=prod

npx nx apply tf-infra --configuration=prod

bunx nx apply tf-infra --configuration=prod

You can also swap environment at any time as the state segments the tfstate automatically between environments.

Remote State Bootstrap (Application Projects Only)

For application projects, before deploying your infrastructure, you’ll need to bootstrap the remote state backend. This creates an S3 bucket to store your Terraform state files:

pnpm

pnpm nx bootstrap tf-infra

yarn

yarn nx bootstrap tf-infra

npm

npx nx bootstrap tf-infra

bun

bunx nx bootstrap tf-infra

AWS Profile Configuration

Ensure your AWS CLI profile is configured to the account/region you wish to deploy the bootstrap resources into.

The bootstrap target is only available for application type projects. Library projects don’t require remote state management as they are designed to be reusable modules.

Available Targets

The available targets depend on your project type:

Common Targets (Both Application and Library)

Validating your Infrastructure

You can validate your Terraform configuration using the validate target:

pnpm

pnpm nx validate tf-infra

yarn

yarn nx validate tf-infra

npm

npx nx validate tf-infra

bun

bunx nx validate tf-infra

Formatting your Code

Format your Terraform code using the fmt target:

pnpm

pnpm nx fmt tf-infra

yarn

yarn nx fmt tf-infra

npm

npx nx fmt tf-infra

bun

bunx nx fmt tf-infra

Security Testing

Run security checks on your infrastructure using Checkov with the test target:

pnpm

pnpm nx test tf-infra

yarn

yarn nx test tf-infra

npm

npx nx test tf-infra

bun

bunx nx test tf-infra

You will find your security test results in the root dist folder, under dist/packages/<my-terraform-project>/checkov.

Application-Only Targets

The following targets are only available for application type projects:

Planning your Infrastructure

Before applying changes, you can see what Terraform will do by running the plan target:

pnpm

pnpm nx plan tf-infra

yarn

yarn nx plan tf-infra

npm

npx nx plan tf-infra

bun

bunx nx plan tf-infra

This will create a plan file in dist/packages/<my-terraform-project>/terraform/dev.tfplan.

Initializing Terraform

Initialize your Terraform working directory with the init target:

pnpm

pnpm nx run tf-infra:init

yarn

yarn nx run tf-infra:init

npm

npx nx run tf-infra:init

bun

bunx nx run tf-infra:init

Deploying to AWS

After planning, you can deploy your infrastructure to AWS using the apply target:

pnpm

pnpm nx apply tf-infra

yarn

yarn nx apply tf-infra

npm

npx nx apply tf-infra

bun

bunx nx apply tf-infra

Auto-Approve

The above command applies the plan created by the plan target. Make sure to run plan first to review the changes.

Getting Outputs

Retrieve output values from your Terraform configuration:

pnpm

pnpm nx output tf-infra

yarn

yarn nx output tf-infra

npm

npx nx output tf-infra

bun

bunx nx output tf-infra

Destroying Infrastructure

When you need to tear down your infrastructure, use the destroy target:

pnpm

pnpm nx destroy tf-infra

yarn

yarn nx destroy tf-infra

npm

npx nx destroy tf-infra

bun

bunx nx destroy tf-infra

Destructive Operation

This will permanently delete all resources managed by this Terraform configuration. Use with caution!

Destroying Bootstrap Resources

To clean up the bootstrap resources (S3 bucket for state storage):

pnpm

pnpm nx bootstrap-destroy tf-infra

yarn

yarn nx bootstrap-destroy tf-infra

npm

npx nx bootstrap-destroy tf-infra

bun

bunx nx bootstrap-destroy tf-infra

More Information

For more information about Terraform, please refer to the Terraform Documentation and AWS Provider Documentation.